快速开始

wxa-runner 在普通的 Chrome 里，用微信官方基础库运行小程序：用 Chrome DevTools 调试，用 Playwright 写自动化测试。它不替代微信开发者工具，预览、上传、真机调试仍然要用开发者工具，区别见功能与限制。

需要 Node.js ≥ 18。基础库和编译器不用另外准备，见下文。

启动

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

bash

npx wxa-runner dev . --open

先运行 uni-app 的监听构建，再在另一个终端里启动编译产物目录：

bash

# 终端 1：uni-app 的监听构建
npm run dev:mp-weixin

# 终端 2
npx wxa-runner dev ./dist/dev/mp-weixin --open

HBuilderX 创建的项目，编译产物在 unpackage/dist/dev/mp-weixin。改了源码后 uni-app 重新构建，wxa-runner 自动热更新。

和 uni-app 一样：先运行框架的监听构建，再把编译产物目录传给 wxa-runner dev。

[wxa-runner] 编译完成：3 个页面，1 个组件，17ms

  wxa-runner 已启动
  地址      http://localhost:3000
  项目      /path/to/my-app
  基础库    3.7.0

浏览器里是一台模拟的手机（默认 iPhone X），有导航栏和 tabBar，可以像在模拟器里一样点击、滚动
地址加上 ?path= 直接打开某个页面，其余参数作为页面参数：http://localhost:3000/?path=pages/detail/detail&id=1
需要登录才能进的页面，用 setup 预置登录态

经常用或者要在 CI 里跑，装成开发依赖：pnpm add -D wxa-runner（或 npm i -D wxa-runner）。

打开 Chrome DevTools（macOS 上 Cmd+Option+I，Windows 上 F12）：

打断点：在 Sources 面板按 Cmd+P（Windows 上 Ctrl+P），输入文件名（如 pages/index/index）找到业务代码。每个 JS 文件单独加载，行号和源文件一致；用 import / export 写的文件带 source map
调用栈：基础库的代码已加入 DevTools 的忽略列表，报错时的调用栈、单步调试都停在业务代码上，不会跳进基础库
控制台：App、Page 的代码运行在逻辑层的 iframe 里。要在控制台里调用 getCurrentPages()、wx.xxx，先把控制台左上角的上下文从 top 切换到 wxa-appservice（appservice.html）
网络：wx.request 由开发服务器转发，在 Network 面板里显示为 /__wxa__/proxy?url=…。被 setup 拦截的请求不发出，不会出现在这里，控制台会打印 [wxa-runner] 拦截请求
页面结构：每个页面是一个 iframe，在 Elements 面板里能看到渲染出的节点和样式

本机有微信开发者工具就用它的，没有就用随依赖安装的内置版本，不用另外准备。

内置基础库从 GitHub 安装（wxa-baselib），需要本机有 git、能访问 github.com。访问不了时安装不会报错，只是没有内置基础库，在没有开发者工具的机器上启动时会提示找不到基础库
默认使用基础库 3.7.0 及以下的版本。3.7.1 起的版本要用 --baselib 或 WXA_BASELIB 指定，见命令与环境变量