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 等价，选择任一前缀即可。

从当前版本开始，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 | 云开发命令 |

官方文档：

• https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html

其中 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