跳到正文

命令与环境变量 ​

命令作用
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 ​

bash
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)

常见用法:

bash
# 原生小程序,启动后打开浏览器
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:

ts
// 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-watchfalse 时不监听文件变化
setup--setup / --no-setupsetup 文件,false 时不执行
devtoolsLogin--devtools-login借用开发者工具登录态
forwardConsole--forward-console / --no-forward-consoletrue 时 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 运行时也能用:

ts
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 的环境变量

基于 MIT 许可发布。内置基础库是微信官方代码,版权归腾讯所有