一行命令把 uni-app 微信小程序塞进 Chrome 调试

发版前最让人憋屈的一件事，往往不是代码有 bug，而是回归跑不起来。小程序要测，就得先开微信开发者工具；开发者工具只有 Windows 和 macOS 桌面版，Linux 流水线里想加一条端到端用例，最后通常变成「专门养一台带图形界面的测试机」。提交触发的 CI 卡在这里，人工点一遍又累且不可持续。open-wxa 组织下的开源项目 wxa-runner，补的就是这个缺口——用微信官方基础库渲染，Playwright 无头 E2E 测试，Chrome DevTools 调试，CI 里不装开发者工具也能跑。

换的不是框架，是宿主

官方的 miniprogram-automator 要先启动开发者工具、打开服务端口再远程控制它，系统被锁在 Windows 和 macOS，真机自动化虽在，CI 门槛却高。wxa-runner 把运行宿主从「微信开发者工具」换成了「普通 Chrome」，于是 Playwright 的 Trace、自动重试、并发这些现成能力全都能直接用，Linux Docker 里 npx playwright test 就是一条普通用例。

最容易被误读的是「在浏览器里跑小程序」。它不是把 uni-app 再编译成一套 H5，也不是用 Vue 重写一遍组件系统。项目直接加载微信官方的 WAService.js 和 WAWebview.js，WXML、WXSS、WXS 交给官方编译器 wcc 与 wcsc 处理，App、Page、Component、exparser、setData 与生命周期全由基础库自己的代码执行。逻辑层和渲染层各是一个同源 iframe，中间用 WeixinJSBridge 通信，宿主只补齐微信客户端那部分原生能力——十层页面栈、导航栏、tabBar、弹窗、wx.* API 注册表，以及把 wx.request 经本地服务转发以绕开 CORS。渲染层向基础库声明平台为 devtools，基础库便自动启用为官方工具准备的 Web 端实现。

所以那句「和真机一致」的准确含义是，跑的是同一份官方代码，只是外壳从微信客户端换成了 Chrome。

一行命令，两个终端

环境只要 Node.js ≥ 18，基础库和编译器随依赖装好，本机装过开发者工具就优先复用它下载的版本，没有就用内置的 3.7.0。

# 原生小程序，在 project.config.json 所在目录
npx wxa-runner dev . --open
# uni-app：终端 1 起框架监听构建
npm run dev:mp-weixin
# 终端 2 指向编译产物目录
npx wxa-runner dev ./dist/dev/mp-weixin

默认打开 http://localhost:3000，浏览器里是一台带导航栏和 tabBar 的模拟手机。想看深层页面不必从首页一路点进去，地址加 ?path=pages/detail/detail&id=1 就能直达，其余查询参数自动当页面参数。Taro 同理传 mp-weixin 产物目录即可。官网还挂了免安装在线预览，打开就是一个 uni-app 小程序，投票、评论、发帖都能操作，接口全由 setup 用 mock 数据应答，刷新后恢复原样。

调试像 Web，测试像 Web

按 F12 打开 DevTools，业务 JS 每个文件单独加载、行号与源文件对齐，ES module 经 esbuild 转换并带 source map，基础库脚本被加进忽略列表，断点和调用栈都停在业务代码而不是 WAService.js 里。唯一容易漏的一步是把控制台上下文从 top 切到逻辑层 iframe，否则敲 getCurrentPages() 会报未定义。

热更新也做了细分：改 WXSS 立即生效且不动 data，改 WXML 用当前 data 重渲染，改 Page 的 JS 只替换方法、onLoad 不重跑，改 Component 的 JS 只重新挂载这一个组件，其余改动整页刷新并恢复页面栈。启动前的 wxa.setup.ts 更实用，在 App.onLaunch 之前预置 storage 和登录态、按名替换原生 API、按 URL 规则拦截 wx.request，业务代码一行不用改就能跳过登录。

测试侧由 @open-wxa/wxa-runner-playwright 提供 miniProgram fixture，负责起服务、开浏览器、等启动完成；toHavePath、toHavePageData 会自动重试，waitForRequest 能拿到请求体做断言，用例结束还会检查未捕获报错和调用过的未实现 API。

边界比能力更该先读

它不替代微信开发者工具，扫码预览、代码上传、真机调试仍要回官方工具。内置基础库只有 3.7.0，3.7.1 起要用 --baselib 指定且属未验证范围；装完依赖最好跑一次 npx wxa-runner baselib list，因为内置库安装失败是静默的，往往到无开发者工具的机器上才暴露。蓝牙、NFC 等硬件能力，插件自定义组件、Skyline、Worker 同步接口、部分 map 与 web-view 场景都有限制，无开发者工具环境还只支持 x86-64。

说到底，它测的是逻辑与交互——业务流程、页面 data、发出的请求，而不是真机像素或机型适配。发版前最后一遍，仍请在真机上走完。

项目自身以 MIT 开源，从源码构建、跑示例和测试见仓库的 CONTRIBUTING.md，Issue 和 PR 都欢迎。但合规上要留个心：内置的 wxa-baselib 是微信官方代码，版权归腾讯所有，不适用本项目的 MIT 协议。

把它放在开发者工具旁边当一台更轻的「浏览器副驾」，日常联调和 CI 回归会顺手很多。