一份面向 Windows 开发环境的实践说明：让微信开发者工具桌面端保持可见，同时通过 CLI 完成登录检查、云环境查询、预览与上传，并使用 miniprogram-automator 读取页面、点击控件和保存截图。
本仓库不绕过微信登录或权限。首次扫码登录、开启服务端口、授权弹窗以及部分云控制台设置仍需开发者本人操作。
- CLI 一直等待，或者回调到
localhost后提示拒绝连接。 - 不清楚开发者工具桌面端和 CLI 能否同时打开。
- 想让自动化脚本读取当前页面并截图，但不知道如何连接自动化端口。
- 想把登录检查、云函数部署、预览、上传等操作做成可复用脚本。
需要区分两条本地连接：
| 通道 | 示例端口 | 用途 |
|---|---|---|
| 开发者工具服务端口 | 55975 |
CLI 登录检查、云能力、预览、上传 |
| 自动化 WebSocket 端口 | 9420 |
页面读取、点击、输入、截图 |
两条通道连接同一个微信开发者工具实例。桌面端、CLI 和自动化脚本可以同时工作，并不是互斥的三个环境。
端口仅为示例。服务端口必须以开发者工具“设置 → 安全设置 → 服务端口”中实际显示的值为准。
- Windows 10/11
- 微信开发者工具
- Node.js 与 npm
- 一个可以在开发者工具中正常编译的小程序项目
本文用 PowerShell 演示。请将下面路径替换为自己的实际路径：
$cli = "D:\path\to\微信web开发者工具\cli.bat"
$project = "D:\path\to\your-miniprogram"
$servicePort = 55975
$automationPort = 9420$project 应指向 project.config.json 所在目录。
- 打开微信开发者工具并导入项目。
- 进入“设置 → 安全设置”。
- 开启“服务端口”。
- 记录开发者工具显示的端口号。
- 确认当前开发者工具已经登录正确账号。
服务端口关闭或端口号不一致，是 CLI 卡住和 ERR_CONNECTION_REFUSED 最常见的原因。
# 检查登录状态；成功时会返回 {"login":true}
& $cli islogin `
--project $project `
--port $servicePort `
--lang zh
# 查询可用云环境
& $cli cloud env list `
--project $project `
--port $servicePort `
--lang zh只要这两个只读命令能够完成，就说明 CLI 通道已经可用。
& $cli auto `
--project $project `
--auto-port $automationPort `
--trust-project `
--port $servicePort `
--lang zh开发者工具仍然可以保持打开。自动化脚本通过 ws://127.0.0.1:9420 连接当前实例。
安装依赖：
npm install运行仓库中的示例：
$env:WECHAT_AUTOMATION_PORT = "9420"
npm run inspect成功后，终端会打印当前页面路径，并在 artifacts/latest.png 保存截图。
核心代码如下：
const automator = require("miniprogram-automator");
const miniProgram = await automator.connect({
wsEndpoint: "ws://127.0.0.1:9420",
});
const page = await miniProgram.currentPage();
console.log(page.path);
await miniProgram.screenshot({ path: "artifacts/latest.png" });
miniProgram.disconnect();首次验证建议只调用 currentPage() 和 screenshot()。部分页面包含云请求或复杂数据时，直接读取完整 page.data() 可能等待较久。
下面命令会影响预览文件或云端状态，执行前请检查项目、环境、版本号和描述。
# 生成预览二维码
& $cli preview `
--project $project `
--qr-format image `
--qr-output "$PWD\preview.png" `
--port $servicePort `
--lang zh
# 上传小程序版本
& $cli upload `
--project $project `
--version "0.1.0" `
--desc "功能更新" `
--port $servicePort `
--lang zh
# 云函数部署示例，请替换环境 ID 和函数名
& $cli cloud functions deploy `
--env "your-cloud-env-id" `
--names "yourFunction" `
--remote-npm-install `
--project $project `
--port $servicePort `
--lang zh不同开发者工具版本的参数可能变化，正式操作前可运行 & $cli --help 或相应子命令的帮助信息确认。
- 检查服务端口是否已经打开。
- 检查命令中的
--port是否与界面显示一致。 - 确认命令指向正确的
cli.bat和项目目录。 - 不要把自动化端口误当成服务端口。
- 确认已经执行
cli.bat auto。 - 检查自动化端口是否被其他进程占用。
- 自动化接口通常只需要一个活动客户端。
- 上一次调试异常退出时，只结束自己能够明确识别的残留 Node 调试进程，不要批量结束系统进程。
不需要。服务端口开启后，桌面端和 CLI 可以同时运行。电脑重启或完全退出开发者工具后，重新打开项目并开启自动化连接即可。
以开发者工具当前显示值为准，同时修改 CLI 命令和本地脚本中的服务端口。自动化端口可以自行指定，只要没有端口冲突即可。
可以提交到代码仓库：自动化脚本、命令说明、页面代码、云函数代码和不包含秘密的项目配置。
不要提交：微信私钥、访问令牌、登录二维码、用户 OpenID 导出数据、数据库备份、真实用户上传内容、node_modules、缓存和自动化截图。
miniprogram-automator 应仅作为本地开发依赖使用。其当前最新版仍包含一些较旧的传递依赖，npm 可能显示安全审计警告；不要把服务端口或自动化端口暴露到公网，也不要对不受信任的项目开放自动化权限。