npm.io
5.4.11 • Published 4h agoCLI

weapp-ide-cli

Licence
MIT
Version
5.4.11
Deps
11
Size
256 kB
Vulns
0
Weekly
0
Stars
358
SummaryDependencyVersions

weapp-ide-cli

weapp-ide-cli 是对「微信开发者工具」官方命令行的增强封装，提供更友好的参数体验、路径兼容与配置管理能力，帮助你在本地与持续集成环境中高效调用工具链。

功能亮点

  • 自动识别或记忆微信开发者工具 cli 所在位置，避免反复输入路径。
  • 为 -p / --project、--qr-output 等选项自动补全绝对路径，默认使用当前工作目录。
  • 使用与官方指令完全一致的调用方式，便于在脚本中无缝迁移。
  • 在 open / auto / auto-preview / automator 启动前，自动预热微信开发者工具安全设置，并可自动信任目标项目。
  • 支持 macOS、Windows 以及安装了社区版工具的 Linux 桌面环境。
  • 内置支付宝小程序 CLI 入口，直接转发至官方 minidev 工具。

安装

# 使用 pnpm
pnpm add -g weapp-ide-cli

# 或使用 npm
npm install -g weapp-ide-cli

# 或使用 yarn
yarn global add weapp-ide-cli

快速开始

# 打开微信开发者工具（项目目录为当前终端所在位置）
weapp open -p

# 启动并加载指定项目
weapp open --project ./dist/dev/mp-weixin

# 显式要求信任项目
weapp open --project ./dist/dev/mp-weixin --trust-project

# 执行预览、上传等官方支持的命令
weapp preview
weapp upload --project ./dist/build/mp-weixin
weapp cache --clean compile
weapp cache --clean all

weapp 与 weapp-ide-cli 等价，选择任一前缀即可。

AI / MCP 直接调用

weapp-ide-cli 内置 MCP Server，可让支持 MCP 的 AI 客户端直接连接微信开发者工具 automator 会话，进入模拟器执行页面检查、元素定位、点击、输入、截图与基础 E2E 验证。

AI 客户端建议使用 stdio 配置：

{
  "mcpServers": {
    "weapp-ide-cli": {
      "command": "weapp",
      "args": [
        "mcp",
        "--workspace-root",
        "<repo-root>"
      ]
    }
  }
}

也可以直接启动：

weapp mcp --workspace-root .

启动后 AI 可以直接调用这些工具：

MCP Tool 说明
weapp_devtools_connect 连接 DevTools 并读取当前页
weapp_devtools_active_page 获取当前页、尺寸、data
weapp_devtools_page_stack 获取页面栈
weapp_runtime_find_node 查询单个元素并返回快照
weapp_runtime_find_nodes 查询多个元素并返回快照
weapp_runtime_tap_node 点击元素
weapp_runtime_input_node 向元素输入文本
weapp_devtools_capture 截取模拟器当前视口
weapp_devtools_host_api 调用基础 wx.* API

推荐调用顺序：

  1. weapp_devtools_connect
  2. weapp_devtools_active_page
  3. weapp_runtime_find_node / weapp_runtime_find_nodes
  4. weapp_runtime_tap_node / weapp_runtime_input_node
  5. weapp_devtools_capture

首次使用前请确保微信开发者工具已登录，并已开启「设置 -> 安全设置 -> 服务端口」。

从当前版本开始，weapp-ide-cli 会在调用微信开发者工具前自动尝试预热本机 DevTools 配置：

  • 确保安全设置里启用服务端口
  • 根据命令或全局配置决定是否自动信任项目

在 macOS 上，它会写入 ~/Library/Application Support/微信开发者工具/*/WeappLocalData 下对应的本地配置；如果你不希望自动处理，也可以通过下文的 config 配置项关闭。

支付宝小程序（minidev）支持

封装内置了支付宝官方 CLI —— minidev 的调用入口，可通过 weapp alipay 或 weapp ali 直接转发指令：

# 调用 minidev 登录
weapp alipay login

# 预览支付宝小程序
weapp alipay preview --project ./dist/mp-alipay

首次使用前请确认已全局安装 minidev（例如执行 pnpm add -g minidev）。若命令不存在，CLI 会给出安装提示。

也支持通过 open 命令直接指定平台为支付宝，此时会自动转发到 minidev ide：

weapp open --platform alipay -p ./dist/dev/mp-alipay

命令大全

1. 微信官方 CLI 透传命令（V2）

下列命令会透传到微信开发者工具官方 CLI（weapp 只在外层补了路径兼容、配置与错误处理）：

命令 说明
weapp open 打开 IDE / 项目
weapp login 重新登录 IDE
weapp islogin 检查登录状态
weapp preview 预览二维码
weapp auto-preview 自动预览
weapp upload 上传小程序
weapp build-npm 构建 npm
weapp auto 开启自动化
weapp auto-replay 自动化回放
weapp reset-fileutils 重置文件工具
weapp close 关闭项目
weapp quit 退出 IDE
weapp cache 清理缓存
weapp engine 引擎相关命令
weapp open-other 打开其它项目
weapp build-ipa 生成 iOS 包
weapp build-apk 生成 Android 包
weapp cloud 云开发命令

官方文档：

其中 weapp cloud 为云开发命令族入口，可继续透传官方子命令，例如：

weapp cloud env list
weapp cloud functions list
weapp cloud functions info --name hello
weapp cloud functions deploy --name hello
weapp cloud functions inc-deploy --name hello
weapp cloud functions download --name hello

缓存清理示例：

weapp cache --clean compile
weapp cache --clean network
weapp cache --clean all

支持的缓存类型：

  • storage
  • file
  • compile
  • auth
  • network
  • session
  • all
2. automator 增强命令

weapp-ide-cli 内置 automator 子命令：

命令 说明
weapp screenshot 截图（支持 base64 / 文件输出）
weapp compare 截图对比（pixelmatch）
weapp navigate <url> 保留栈跳转页面
weapp redirect <url> 重定向页面
weapp back 页面返回
weapp relaunch <url> 重启到指定页面
weapp switch-tab <url> 切换到 tabBar 页
weapp page-stack 查看页面栈
weapp current-page 查看当前页面
weapp system-info 查看系统信息
weapp page-data [path] 查看页面数据
weapp tap <selector> 点击元素
weapp input <selector> <value> 元素输入
weapp scroll <scrollTop> 页面滚动
weapp audit 体验评分审计
weapp remote [--disable] 开关远程调试

帮助查看方式：

weapp help navigate
weapp navigate --help
3. config 子命令
命令 说明
weapp config 交互式配置 CLI 路径
weapp config lang <zh|en> 切换并保存语言
weapp config set-lang <zh|en> lang 的别名
weapp config show 显示完整配置 JSON（含生效默认值）
weapp config get <cliPath|locale|autoBootstrapDevtools|autoTrustProject> 读取单个配置项
weapp config set <cliPath|locale|autoBootstrapDevtools|autoTrustProject> <value> 写入配置项
weapp config unset <cliPath|locale|autoBootstrapDevtools|autoTrustProject> 删除配置项
weapp config doctor 配置健康诊断（含生效默认值）
weapp config export [path] 导出配置（不传 path 则输出 stdout）
weapp config import <path> 从 JSON 文件导入配置
4. 支付宝 minidev 转发命令
命令 说明
weapp alipay <args...> 透传到 minidev
weapp ali <args...> alipay 别名
weapp open --platform alipay ... 自动转发为 minidev ide ...
5. 程序化命令目录导出

可在 Node 侧直接复用 weapp-ide-cli 的命令目录判断能力：

import {
  isWeappIdeTopLevelCommand,
  WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES,
} from 'weapp-ide-cli'

if (isWeappIdeTopLevelCommand('preview')) {
  // 命中 weapp-ide-cli 顶层命令，可执行透传
}

console.log(WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES)
6. 程序化 opened-session helper

除了官方 CLI 透传和 automator 子命令，weapp-ide-cli 也提供了一组面向「已打开 DevTools 会话」的 helper。它们会优先复用当前项目对应的会话，在官方 HTTP / Tool 域能力可用时直接下发指令，减少再次拉起 IDE 或误打开项目选择页的概率。

当前适合通过 helper 复用的能力包括：

  • 获取当前 DevTools Tool 信息
  • 通过已打开会话触发重新编译
  • 通过已打开会话清理 compile / all 等缓存
  • 获取、设置、刷新当前 ticket
  • 获取当前测试账号列表

如果你在用 weapp-vite，更推荐直接使用高层入口：

  • wv ide info
  • wv ide test-accounts
  • wv ide ticket
  • wv ide ticket:set --ticket <value>
  • wv ide ticket:refresh

weapp-ide-cli 负责底层官方 CLI / HTTP / automator helper 封装，weapp-vite 则提供更适合开发流的终端交互与项目解析。

程序化调用示例：

import {
  clearWechatIdeCacheByAutomator,
  compileWechatIdeByAutomator,
  getWechatIdeTicket,
  getWechatIdeToolInfo,
} from 'weapp-ide-cli'

const projectPath = './dist/dev/mp-weixin'

await compileWechatIdeByAutomator({ projectPath })

const info = await getWechatIdeToolInfo({ projectPath })
const ticket = await getWechatIdeTicket({ projectPath })

await clearWechatIdeCacheByAutomator({
  projectPath,
  cleanType: 'compile',
})

console.log(info, ticket)

路径与参数兼容

  • -p 会被自动替换为 --project，并且相对路径会解析为绝对路径。
  • --qr-output、--result-output、--info-output 及其短选项在缺省值时会默认指向当前工作目录。
  • 如果未显式提供路径参数，CLI 会自动注入当前终端所在目录，方便脚本化调用。

配置 CLI 所在位置

执行一次互动式配置即可持久化工具路径：

weapp config

也可以通过命令直接切换语言并写入同一配置文件：

weapp config lang zh
weapp config lang en

配置子命令：

# 查看完整配置（JSON）
weapp config show

# 读取单个配置项
weapp config get cliPath
weapp config get locale
weapp config get autoBootstrapDevtools
weapp config get autoTrustProject

# 设置配置项
weapp config set cliPath /Applications/wechatwebdevtools.app/Contents/MacOS/cli
weapp config set locale en
weapp config set autoBootstrapDevtools true
weapp config set autoTrustProject true

# 清除配置项
weapp config unset cliPath
weapp config unset locale
weapp config unset autoBootstrapDevtools
weapp config unset autoTrustProject

# 诊断配置可用性
weapp config doctor

# 导出 / 导入配置
weapp config export ./weapp-ide-cli.config.json
weapp config import ./weapp-ide-cli.config.json

配置数据保存在用户目录：

  • macOS / Linux：~/.weapp-ide-cli/config.json
  • Windows：C:\Users\<用户名>\.weapp-ide-cli\config.json

可以直接编辑该文件或重新运行 weapp config 来更新路径。当配置文件缺失或留空时，CLI 会尝试按系统默认安装位置自动寻找。

配置文件示例：

{
  "cliPath": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
  "locale": "zh",
  "autoBootstrapDevtools": true,
  "autoTrustProject": false
}

开发者工具自动预热相关配置说明：

  • autoBootstrapDevtools
    • 默认生效值：true
    • 含义：在 weapp open、weapp auto、weapp auto-preview 以及 automator 启动前，自动预写入微信开发者工具安全设置
  • autoTrustProject
    • 默认生效值：false
    • 含义：在未显式传 --trust-project 时，是否默认把目标项目写成已信任

推荐配置：

weapp config set autoBootstrapDevtools true
weapp config set autoTrustProject true

这样以后就可以直接执行：

weapp open --project ./dist/dev/mp-weixin

而不用每次都补 --trust-project。

平台支持与限制

平台 支持情况 默认查找路径
macOS /Applications/wechatwebdevtools.app/Contents/MacOS/cli
Windows C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat
Linux（社区版） 需手动安装 通过 PATH 搜索 wechat-devtools-cli

若所属平台未检测到 CLI，请使用 weapp config 指定安装位置。

在脚本或 CI 中使用

  1. 确保执行环境已安装微信开发者工具，并且当前账号已登录。
  2. 首次运行前可通过 weapp config 写入 CLI 路径，也可在 CI 中直接向 ~/.weapp-ide-cli/config.json 写入。
  3. 在自动化流程中建议加上 --qr-output、--result-output 等参数，以便收集产物或日志。

推荐在 CI 或非交互脚本里显式启用非交互模式，避免登录失效时卡在按键等待：

weapp build-npm -p --non-interactive

登录重试相关参数：

  • --non-interactive：非交互模式，登录失效时直接失败（退出码语义保留为 10）。
  • --login-retry=never|once|always：控制登录失效后的重试策略。
  • --login-retry-timeout=<ms>：交互重试等待超时（默认 30000）。

当检测到以下场景时，会自动启用非交互模式：

  • CI=true
  • stdin 非 TTY

语言切换（默认中文）

weapp-ide-cli 的增强提示、错误信息与 automator 帮助默认使用中文。 可通过 --lang en 切换为英文，也可通过环境变量 WEAPP_IDE_CLI_LANG=en 统一设置。

# 单次命令切换英文
weapp help navigate --lang en

# 环境变量方式
WEAPP_IDE_CLI_LANG=en weapp navigate pages/index/index -p ./mini-app

参数前置校验（增强）

为减少进入微信 CLI 后才失败的情况，weapp-ide-cli 会在本地先做一部分参数校验：

  • upload 必须提供 --version/-v 与 --desc/-d（且值不能为空字符串）
  • preview 的 --qr-format/-f 仅支持 terminal / image / base64
  • preview / upload / auto / auto-preview 需要提供 --project 或 --appid
  • --ext-appid 在未提供 --project 时必须同时提供 --appid
  • --port 必须为正整数
  • --login-retry 仅支持 never / once / always
  • --login-retry-timeout 必须为正整数

常见问题

  • 命令执行后无反应：请确认微信开发者工具已登录，并尝试重新打开工具或升级版本；默认情况下 CLI 会先自动预热服务端口配置。
  • 提示 需要重新登录 或 code: 10：表示微信开发者工具登录态失效。交互模式下可按 r 重试，按 q、Esc 或 Ctrl+C 取消；非交互模式（含 CI / 非TTY）会直接失败返回非 0。
  • 不想自动改本机 DevTools 配置：执行 weapp config set autoBootstrapDevtools false 关闭默认预热；如只想关闭默认自动信任项目，可执行 weapp config set autoTrustProject false。
  • 提示未找到 CLI：检查配置文件中的路径是否真实存在，可使用绝对路径避免解析误差。
  • Linux 环境报错：需安装社区版工具并将 wechat-devtools-cli 加入 PATH，否则只能手动指定路径。
  • upload 报参数缺失：weapp upload 现在会在本地前置校验 --version/-v 与 --desc/-d，缺失时直接报错以避免触发远端失败。

贡献

欢迎通过 Issues 或 Pull Request 提交优化建议，开发前请阅读仓库根目录的 CONTRIBUTING.md。

许可证

MIT

Keywords

weappweapp-cliwechatcliuni-apptaroideweapp-ideminiminiprogram