跳到正文

快速开始 ​

wxa-runner 在 Chrome 里用微信官方基础库运行小程序。需要 Node.js ≥ 18,基础库和编译器不用另外装。

启动 ​

原生小程序 ​

在 project.config.json 所在目录运行:

bash
npx wxa-runner dev . --open

uni-app ​

装上 Vite 插件,npm run dev:mp-weixin 时自动启动 wxa-runner:

bash
pnpm add -D @open-wxa/unplugin-wxa-runner @open-wxa/wxa-runner-core
ts
// vite.config.ts
import uni from '@dcloudio/vite-plugin-uni';
import wxaRunner from '@open-wxa/unplugin-wxa-runner/vite';

export default defineConfig({
  plugins: [uni(), wxaRunner()]
});

首轮编译完成后终端打印 wxa-runner 的地址,改了源码页面会自动热更新。 插件要求 Node.js 20.19 / 22.12 及以上,端口、setup 等选项见插件文档。

不用插件:两个终端分别启动
bash
npm run dev:mp-weixin                            # 终端 1
npx wxa-runner dev ./dist/dev/mp-weixin --open   # 终端 2

HBuilderX 创建的项目,产物在 unpackage/dist/dev/mp-weixin。

Taro 等其他框架:先跑框架的监听构建,再用 npx wxa-runner dev <编译产物目录> 启动。


浏览器里会出现一台模拟手机,可以像模拟器一样点击、滚动。接下来常用的:

  • 直接打开某一页:http://localhost:3000/?path=pages/detail/detail&id=1
  • 跳过登录:见启动前准备(setup)
  • 长期使用或在 CI 里跑:装成开发依赖 pnpm add -D wxa-runner

调试 ​

打开 Chrome DevTools(macOS Cmd+Option+I,Windows F12):

想做什么怎么做
打断点Sources 面板按 Cmd+P(Windows Ctrl+P),输入文件名,如 pages/index/index
在控制台调用 getCurrentPages()、wx.xxx先把控制台左上角的上下文从 top 切到 wxa-appservice
看 wx.requestNetwork 面板,地址形如 /__wxa__/proxy/https/api.example.com/user/info
看页面结构Elements 面板,每个页面是一个 iframe

报错和单步调试停在业务代码上,不会跳进基础库。

被 setup 拦下的请求在 Network 里是什么样

显示为 /__wxa__/mock/https/…,控制台同时打印 [wxa-runner] 拦截请求。 它们靠 Service Worker 显示:第一次打开页面时,它装好之前的请求不显示;强制刷新(Shift+Reload)后、用局域网 IP 访问时不显示。请求本身不受影响。

下一步 ​

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