微信小程序 wechat-devtools-mcp 安装文档

grin_star

254人浏览 · 2026-11-03 23:41:40

grin_star · 2026-11-03 23:41:40 发布

微信小程序 wechat-devtools-mcp 安装文档

参考文章：微信小程序自动化的 AI 新时代：wechat-devtools-mcp 智能方案
本机环境：Windows 11、Node.js v24.19.0、微信开发者工具 2.01.2510290
本文档基于实际安装过程整理，包含文章未提及的 3 个 Windows 兼容性坑及解决办法。

一、前置条件

依赖	说明	本项目实际情况
Node.js	建议 v18+（v24 实测可用，需补丁，见第四节）	v24.19.0
微信开发者工具	需安装并登录，记下安装目录下 `cli.bat` 路径	`D:\wechatAppDevTool\微信web开发者工具\cli.bat`
小程序项目	包含 `project.config.json` 的项目根目录	`C:\Users\15808\Desktop\1031project\miniapp`

必须开启服务端口：微信开发者工具 → 设置 → 安全设置 → 服务端口 → 开启。
不开会导致一切 CLI/MCP 调用报 IDE service port disabled。

二、MCP 配置

wechat-devtools-mcp 是 npm 包（wechat-devtools-mcp@0.0.1），通过 npx 运行，无需全局安装。

在 MCP 配置文件（本项目中为 .trae/mcp.json，Claude/Cursor 为其各自的 mcp 配置文件）中添加：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "npx",
      "args": [
        "-y", "wechat-devtools-mcp",
        "--projectPath=C:/Users/15808/Desktop/1031project/miniapp",
        "--cliPath=D:/wechatAppDevTool/微信web开发者工具/cli.bat"
      ],
      "env": {
        "NODE_OPTIONS": "--require=C:/Users/15808/Desktop/1031project/.trae/wechat-devtools-mcp-compat.cjs"
      }
    }
  }
}

命令行参数

参数	类型	说明
`--projectPath`	string	小程序项目路径（必填，建议绝对路径）
`--cliPath`	string	微信开发者工具 CLI 路径（默认找 `C:/Program Files (x86)/Tencent/微信web开发者工具/cli.bat`，非默认安装位置必须指定）
`--timeout`	number	连接超时毫秒数，默认 30000
`--port`	number	WebSocket 端口号，默认 9420
`--account`	string	用户 openid
`--ticket`	string	开发者工具登录票据
`--projectConfig`	string	覆盖 project.config.json 中的配置（JSON 字符串）

三、验证安装

重启编辑器（或刷新 MCP 列表），在弹窗中允许 wechat-devtools 启动。
每次会话先调用 launch 工具启动并连接小程序，成功返回「小程序已启动并连接」。
之后可用 58 个工具，常用：

类别	工具
导航	`navigateTo` / `redirectTo` / `navigateBack` / `reLaunch` / `switchTab` / `pageStack` / `currentPage`
元素操作	`getElement` / `tapElement` / `inputElement` / `getElementText` / `getElementAttribute` / `waitFor`
页面数据	`getPageData` / `setPageData` / `callPageMethod`
调试	`getlogs` / `getexceptions` / `screenshot` / `systemInfo` / `evaluate`
微信 API	`callWxMethod` / `mockWxMethod` / `restoreWxMethod` / `testAccounts` / `stopAudits`

四、Windows 兼容性坑（文章未写，本项目实测）

按文章直接配置会在 launch 时报错，原因是 npm 包长期未更新，与新环境不兼容。已在 .trae/wechat-devtools-mcp-compat.cjs 中通过 NODE_OPTIONS --require 预加载 shim 解决：

坑 1：服务端口未开启

现象：IDE service port disabled，CLI 卡在 Enable IDE Service (y/N)。
解决：开发者工具设置里手动开启服务端口；或改用户数据目录下 WeappLocalData\localstorage_*.json 与 ls_*.json 中的 "security":{"enableServicePort":true}（需先关闭工具再改）。

坑 2：Node ≥ 18.20/20.12 禁止无 shell spawn .bat

现象：launch 报 Failed to launch wechat web devTools, please make sure cliPath is correctly specified，实际是 spawn EINVAL。
原因：miniprogram-automator 直接 child_process.spawn(cli.bat)，新版 Node 出于安全禁止。
解决：compat shim 中对 .bat/.cmd 的 spawn 自动补 shell: true。

坑 3：新版开发者工具 `Tool.getInfo` 不再返回 `SDKVersion`

现象：launch 报 TypeError: Cannot read properties of undefined (reading 'split')。
原因：automator 0.12.1 的 checkVersion() 读取 SDKVersion 做版本比较，2.01 版本工具只返回 {version}。
解决：compat shim 中将 MiniProgram.prototype.checkVersion 置空跳过校验（功能不受影响）。

注意：cli.bat auto 是同步命令，执行完即退出，自动化 WebSocket 端口由 IDE 进程维持——必须先有开发者工具实例在运行（launch 工具会自动拉起）。

五、典型使用流程

launch                          # 启动并连接（前置条件）
currentPage                     # 确认当前页面
navigateTo { url: '/pages/detail/detail?id=123' }
getElementText { selector: '.title' }
tapElement { selector: '.submit-button' }
getlogs { type: 'error', limit: 10 }
screenshot                      # 返回 base64 截图