CLI 命令参考

本文汇总 weapp-vite 在当前版本可用的命令与参数，优先覆盖日常开发、构建、支持文件预生成、AI 协作与 IDE 自动化场景。

需要调用微信开发者工具能力（preview/upload/automator/config 等）时，weapp-vite 会在未命中自身命令后自动透传到 weapp-ide-cli。

weapp-vite CLI 也提供简写命令 wv。weapp-vite dev 与 wv dev、weapp-vite build 与 wv build 都是等价写法。下文统一使用 weapp-vite 作为主示例。

命令格式

weapp-vite [全局参数] <command> [command options]
# 或
wv [全局参数] <command> [command options]

默认命令是 dev，也就是：

weapp-vite
wv

等价于：

weapp-vite dev

全局参数

参数	说明
-c, --config <file>	指定配置文件
--base <path>	公共基础路径（默认 /）
-l, --logLevel <level>	日志级别：info/warn/error/silent
--clearScreen	控制是否清屏输出
-d, --debug [feat]	启用调试日志（可选调试分组）
-f, --filter <filter>	过滤调试日志
-m, --mode <mode>	运行模式（如 development / production）

原生命令

1) dev / serve（默认命令）

用于本地开发与监听构建。

weapp-vite dev [root]
weapp-vite serve [root]
weapp-vite [root]
# 等价写法
wv dev [root]
wv serve [root]
wv [root]

参数：

参数	说明
--skipNpm	跳过 npm 构建
-o, --open	构建后尝试打开 IDE
-p, --platform <platform>	目标平台（weapp | h5）
--project-config <path>	小程序 project.config.json 路径
--host [host]	Web dev server host（h5 场景）
--analyze	启动分包分析仪表盘（实验特性，小程序场景）

补充说明：

• 当目标平台为 weapp 且启用了 weapp.forwardConsole 时，weapp-vite dev --open 会在打开微信开发者工具后，自动尝试把小程序 console 日志桥接到当前终端。
• 默认配置是 enabled: 'auto'，也就是仅在检测到 AI 终端时自动启用。

2) build

用于生产构建（支持 watch）。

weapp-vite build [root]
# 等价写法
wv build [root]

参数：

参数	说明
--target <target>	构建目标（默认 modules）
--outDir <dir>	输出目录（默认 dist）
-p, --platform <platform>	目标平台（weapp | h5）
--project-config <path>	小程序 project.config.json 路径
--sourcemap [output]	产出 sourcemap（true/inline/hidden）
--minify [minifier]	代码压缩开关或压缩器（false/terser/esbuild）
--emptyOutDir	当 outDir 在 root 外时强制清空
-w, --watch	监听并增量重建
--skipNpm	跳过 npm 构建
-o, --open	构建后尝试打开 IDE
--analyze	输出分包分析仪表盘（小程序场景）

3) analyze

分析小程序分包产物映射，或输出 Web 静态分析结果。

weapp-vite analyze [root]
# 等价写法
wv analyze [root]

参数：

参数	说明
--json	输出 JSON 结果（stdout）
--output <file>	将分析结果写入文件
-p, --platform <platform>	目标平台（weapp | h5）
--project-config <path>	小程序 project.config.json 路径

4) open

打开 IDE（微信或支付宝场景由平台决定）。

weapp-vite open [root]
# 等价写法
wv open [root]

参数：

参数	说明
-p, --platform <platform>	目标平台（weapp | h5 | alipay）

5) ide logs

持续监听微信开发者工具里的小程序日志，并转发到当前终端。

weapp-vite ide logs [root]
# 等价写法
wv ide logs [root]

参数：

参数	说明
-o, --open	先打开微信开发者工具，再附加日志桥
-p, --platform <platform>	目标平台（当前仅支持 weapp）
--project-config <path>	小程序 project.config.json 路径

说明：

• 该命令是常驻进程，按 Ctrl+C 退出。
• 当前仅支持微信小程序平台，不支持 alipay / h5。
• 若你只想在开发时自动附加，而不是手动执行此命令，可直接使用 weapp-vite dev --open 并配合 weapp.forwardConsole。

示例：

weapp-vite ide logs
weapp-vite ide logs --open
weapp-vite ide logs ./dist/dev -p weapp

6) npm（含别名）

调用 IDE 的 npm 构建能力。

weapp-vite npm
weapp-vite build:npm
weapp-vite build-npm
# 等价写法
wv npm
wv build:npm
wv build-npm

7) generate / g

生成 app / page / component 文件骨架。

weapp-vite generate [filepath]
weapp-vite g [filepath]
# 等价写法
wv generate [filepath]
wv g [filepath]

参数：

参数	说明
-a, --app	按 app 模板生成
-p, --page	按 page 模板生成
-n, --name <name>	指定文件名

8) init

初始化项目配置。

weapp-vite init
# 等价写法
wv init

9) prepare

预生成 .weapp-vite 下的支持文件，包括托管 tsconfig、自动路由类型、自动导入组件清单与类型等。

weapp-vite prepare [root]
# 等价写法
wv prepare [root]

适用场景：

• CI 或编辑器启动前，想先把 .weapp-vite 支持文件生成出来；
• 老项目尚未跑过 dev/build，但希望编辑器先拿到类型文件；
• 团队希望把自动路由、自动导入组件相关产物纳入显式预热流程。

10) mcp

启动 weapp-vite MCP 服务（用于 AI 助手接入）。

weapp-vite mcp
# 等价写法
wv mcp

参数：

参数	说明
--transport <type>	传输类型：stdio | streamable-http（默认 stdio）
--host <host>	HTTP 模式监听地址
--port <port>	HTTP 模式端口
--endpoint <path>	HTTP 模式 endpoint（默认 /mcp）
--unref	HTTP 模式下 unref server（不阻塞进程退出）
--workspace-root <path>	指定 workspace 根目录（默认从当前目录自动向上定位）

示例：

weapp-vite mcp
weapp-vite mcp --transport streamable-http --host 127.0.0.1 --port 3088 --endpoint /mcp

不在仓库目录执行时，可选追加 --workspace-root /path/to/weapp-vite。

weapp-ide-cli 透传规则

当你输入的命令不是 weapp-vite 原生命令时，CLI 会判断是否属于 weapp-ide-cli 顶层命令。若命中，则直接透传执行。

weapp-vite 内建命令优先级更高（不会被透传覆盖）：

• dev
• serve
• build
• analyze
• init
• open
• npm
• build:npm
• build-npm
• generate
• g
• ide
• prepare
• mcp

你也可以显式使用命名空间透传：

weapp-vite ide preview --project ./dist -q terminal
weapp-vite ide upload --project ./dist -v 1.0.0 -d "ci upload"
wv ide preview --project ./dist -q terminal
wv ide upload --project ./dist -v 1.0.0 -d "ci upload"

但 weapp-vite 自己保留了 weapp-vite ide logs 这个原生命令，不会透传到 weapp-ide-cli。

完整 IDE 命令列表请参考：

• /packages/weapp-ide-cli

常用示例

# 小程序开发
weapp-vite dev -p weapp
wv dev -p weapp

# Web 开发（指定 host）
weapp-vite dev -p h5 --host 0.0.0.0
wv dev -p h5 --host 0.0.0.0

# 小程序生产构建（不压缩 + 产出 sourcemap）
weapp-vite build -p weapp --minify false --sourcemap
wv build -p weapp --minify false --sourcemap

# 输出分析 JSON 到文件
weapp-vite analyze -p weapp --output ./reports/analyze.json
wv analyze -p weapp --output ./reports/analyze.json

# 预生成 .weapp-vite 支持文件
weapp-vite prepare
wv prepare

# 持续监听 DevTools console
weapp-vite ide logs --open
wv ide logs --open

# 透传微信预览命令
weapp-vite preview --project ./dist -q terminal
wv preview --project ./dist -q terminal