命令与环境变量
| 命令 | 作用 |
|---|---|
wxa-runner dev <项目目录> | 启动开发服务器,在浏览器里运行小程序,改动后热更新 |
wxa-runner baselib list | 列出可用的基础库及兼容性 |
wxa-runner baselib extract [版本] | 解包基础库(dev 会自动执行) |
wxa-runner viewer pack / preview / export | 打包成 .wxapack、在本机打开查看器、导出查看器站点,见查看器(目前只能在仓库里用) |
没装成开发依赖时在前面加 npx,如 npx wxa-runner dev .。
wxa-runner dev
wxa-runner dev [项目目录] [选项][项目目录] 是小程序目录:原生项目的 project.config.json 所在目录,或 uni-app、Taro 等框架编译出的 mp-weixin 目录。配置文件里写了 project 时可以不写。
| 选项 | 默认值 | 作用 |
|---|---|---|
-c, --config <文件> | 自动查找 | 配置文件,路径相对当前目录。不指定时使用当前目录下的 wxa.config.ts / .mts / .js / .mjs / .cjs |
-p, --port <端口> | 3000 | 端口号。默认端口被占用时自动换用后面的端口 |
--host [地址] | localhost | 监听地址。只写 --host 时开放局域网访问 |
-b, --baselib <版本> | 最新的兼容版本 | 基础库版本,见 wxa-runner baselib |
--setup <文件> | 自动查找 | 小程序启动前执行的 setup 文件,路径相对当前目录。不指定时使用项目目录下的 wxa.setup.ts / .js / .mjs |
--no-setup | 不执行 setup 文件 | |
--no-watch | 不监听文件变化、不热更新,运行环境与真机一致。跑测试时用 | |
-o, --open | 启动后打开浏览器 | |
--forward-console | 检测到编程助手时开启 | console.warn / console.error 也转发到终端,见报错转发到终端 |
--no-forward-console | 报错不转发到终端 | |
--devtools-login | 借本机开发者工具的登录态访问微信后台:真实的 wx.login code 和手机号、服务市场 wx.serviceMarket、插件,见借用开发者工具登录态 | |
--extension <模块> | 加载开发服务器扩展,npm 包名或文件路径,可以写多次。从项目目录、当前目录依次查找,扩展提供的页面打印在启动信息里,--open 时打开第一个。如元素检查器:--extension @open-wxa/wxa-inspector(先 npm i -D @open-wxa/wxa-inspector) |
常见用法:
# 原生小程序,启动后打开浏览器
wxa-runner dev . --open
# uni-app:先运行 uni-app 的监听构建,再启动编译产物;setup 文件放在源码目录(用 Vite 插件时不用手动启动)
wxa-runner dev ./dist/dev/mp-weixin --setup ./wxa.setup.ts
# 用指定的基础库版本
wxa-runner dev . --baselib 3.5.8
# 给测试用:不热更新,端口固定
wxa-runner dev . --no-watch --port 3000
# 开放局域网访问
wxa-runner dev . --host配置文件
项目里长期不变的参数写在当前目录的 wxa.config.ts(也可以是 .mts / .js / .mjs / .cjs)里,默认导出一个普通对象,不用引入 wxa-runner:
// wxa.config.ts
export default {
project: './dist/dev/mp-weixin',
setup: './wxa.setup.ts',
port: 3000,
devtoolsLogin: true,
webViewWindow: true,
extensions: ['@open-wxa/wxa-inspector']
};写了之后只要 wxa-runner dev。命令行写了的同名参数优先,如 wxa-runner dev --port 4000。路径都相对配置文件所在目录,用 -c 指定其他位置的配置文件。
| 配置项 | 对应的命令行参数 | 作用 |
|---|---|---|
project | [项目目录] | 小程序目录 |
port | --port | 端口号 |
host | --host | 监听地址,true 时开放局域网访问 |
open | --open | 启动后打开浏览器 |
baselib | --baselib | 基础库版本 |
watch | --no-watch | false 时不监听文件变化 |
setup | --setup / --no-setup | setup 文件,false 时不执行 |
devtoolsLogin | --devtools-login | 借用开发者工具登录态 |
forwardConsole | --forward-console / --no-forward-console | true 时 console.warn / console.error 也转发到终端,false 时报错也不转发 |
extensions | --extension | 开发服务器扩展:npm 包名、文件路径,或 import 进来的扩展(扩展对象,或不带参数调用后返回扩展的函数)。排在命令行的 --extension 之前 |
webViewWindow | 无 | web-view 的网页在新窗口打开,不再嵌在模拟器里。网页和模拟器(localhost)不是同一个站点时,网页的 Cookie 也能正常使用,见 web-view 的 Cookie。命令行的 --webview-window 下个版本移除 |
pageTransition | 无 | 实验性:wx.navigateTo 时新页从右侧滑入,wx.navigateBack 时退出页向右滑出。目前只有页面内容滑动,导航栏和 tabBar 不跟随,在路由切换时直接换成新页面的样子。实际播放动画时,success 会在约 300 ms 的转场结束、页面恢复交互后触发。尊重浏览器的「减少动态效果」设置 |
要类型提示时加上只有类型的引用,运行时不会加载 wxa-runner,用 npx 运行时也能用:
import type { WxaConfig } from 'wxa-runner';
export default {
port: 3000
} satisfies WxaConfig;Playwright 不读配置文件,开发服务器的参数写在 playwright.config.ts 的 wxaServerOptions 里,见测试。
地址带上 ?path= 直接打开指定页面,其余参数作为页面参数:http://localhost:3000/?path=pages/detail/detail&id=1。
报错转发到终端
页面里的报错默认打印到终端,栈只留业务代码:
[wxa-runner] 逻辑层(pages/index/index)报错:Cannot read properties of undefined (reading 'name')
at bo.loadList (pages/index/index.js:9:23)逻辑层在首页创建前出错时(onLaunch 里,或启动阶段的接口回调里),报错后附一行提示:出错时首页还没创建,getCurrentPages() 返回的是空数组。setup 拦截的请求立即返回,回调比真机更容易早于首页执行;需要模拟网络耗时就给拦截规则加 delay。
在编程助手(Claude Code、Codex、Cursor 等)里启动时,console.warn / console.error 也会转发。
wxa-runner baselib
| 命令 | 作用 |
|---|---|
wxa-runner baselib list | 列出可用的基础库:本机开发者工具下载过的和内置的,标出默认使用的版本 |
wxa-runner baselib extract [版本] | 解包基础库到 ~/.wxa-runner/baselib,输出所在目录。内置基础库不用解包,直接输出所在目录 |
基础库的来源和版本:
- 本机微信开发者工具下载过的版本优先;没有时用随依赖安装的内置基础库 3.7.0(wxa-baselib)
- 不指定版本时选最新的兼容版本(≤ 3.7.0)
- 3.7.1 起的版本要用
--baselib或WXA_BASELIB指定,启动时提示超出已验证的范围;内置基础库只有 3.7.0,新版本要先在开发者工具里下载
环境变量
| 变量 | 作用 |
|---|---|
WXA_BASELIB | 没有用 --baselib 指定时使用的基础库版本 |
WXA_DEVTOOLS_PATH | 开发者工具不在默认位置时,指定安装目录(如 macOS 上的 .app 目录),新旧版本都可以 |
WXA_VENDOR_DIR | 指定基础库目录(开发者工具的 WeappVendor) |
WXA_WCC / WXA_WCSC | 直接指定 WXML / WXSS 编译器,优先于开发者工具和 miniprogram-compiler |
WECHAT_DEV_TICKET | --devtools-login 使用的开发者 ticket,优先于开发者工具的登录态 |
WECHAT_DEVTOOLS_CLI_TOKEN | 开发者工具设置了「CLI 访问令牌」时设成它:--devtools-login 调用的开发者工具命令行从这里读取令牌 |
WXA_* | 所有 WXA_ 开头的变量都传给 setup 文件,见 setup 的环境变量 |

