我做了个微信小程序联调工具：把 wx API 的回调数据直接喂给后端

起因

我做这个工具，是因为被微信小程序的前后端联调反复折磨过。

每次和后端同事对接登录、订阅消息、手机号、地图这些能力，基本是这个循环：

前端 wx.login 拿到一段 code
截图或者手抄发到 IM（字段一长就漏）
后端问：”这个字段是什么类型？””还有别的字段吗？””不同基础库一样吗？”
我再回去跑一遍，截图，回复
一个简单的对接能磨半天

更麻烦的是订阅消息——模板 ID 是按小程序绑定的，每个项目都要单独建一套，AppID 一换就全废。后端要测下发，得等我把模板 ID 复制过去，写死到测试代码里，跑一次报一次错，循环。

核心矛盾：微信前端 API 的回调数据非常结构化，但它只在前端跑出来，后端拿不到。我需要一个工具，能在真机/开发者工具里调一次 API，把回调数据原样呈现并复制出来——直接发给后端。

它解决的问题（联调数据视角）

联调死结	传统做法	用这个工具
`wx.login` 的 code 怎么递给后端	截图、手抄、`console.log` 后翻 DevTools	调一次 → 一键复制完整 JSON
订阅消息模板 ID 跨 AppID 不通用	后端写死测试代码，每次改 ID	工具里运行时填 ID，后端只关心回调结构
手机号动态令牌格式每个版本可能变	翻文档、问 AI	真机调一次拿到原始事件对象
`wx.getLocation` 在不同基础库的字段差异	切基础库 → 重启 → 重测	调一次落本地历史，跨版本对比字段
后端要”完整的回调”，但开发者工具显示会截断	让前端多截几张图	弹窗就是 `JSON.stringify(value, null, 2)` 全量

一句话总结：把微信前端 API 的回调数据从”前端私有”变成”前后端可流转的物料”。

给后端的 4 个真实场景

这是这个工具真正能省时间的场景，比”调试 API”更具体：

场景 1：登录对接

后端拿到 code 要去换 session_key 和 openid，但微信的 code 是有时效的（5 分钟），且只能用一次。

前端调 wx.login → 工具弹窗显示：
{
  "code": "081abcDEFghiJKLmnopqrSTUvwx",
  "errMsg": "login:ok"
}

后端同事拿到这段 JSON 后，不用再问字段名、字段类型、是否有嵌套。直接照着写 code2Session 请求体。

工具里的 login 页还支持配置 timeout——后端想看超时回调长什么样，前端设个 1ms 调一次就行。

场景 2：订阅消息下发

订阅消息最烦的是模板 ID——后端拿着空模板 ID 测，永远调不通。

我用这个工具做的事情是：

把自己小程序的模板 ID 输入到工具的 tmplIds 表单
点”订阅” → 工具弹出 wx.requestSubscribeMessage 的回调
回调里能看到 'accept' / 'reject' / 'ban' 各模板 ID 的状态

后端同事要做的只是看回调结构里每个模板 ID 对应的状态字段——他不需要跑前端，也不需要关心模板 ID 是怎么来的。

场景 3：手机号动态令牌

手机号能力受类目限制，但前端拿到的事件对象结构对所有小程序一致：

{
  "detail": {
    "code": "xxx",          // 动态令牌，给后端换手机号
    "encryptedData": "...",
    "iv": "..."
  },
  ...
}

工具的 phone 页用 button open-type="getPhoneNumber" 直接演示这个事件回调。后端同事看到原始字段后，就知道该拿 detail.code 去换手机号，而不是自己再写一个前端 demo。

场景 4：位置与地图

wx.getLocation 的回调在不同基础库有差异——这是历史踩过的坑：

字段	基础库 2.x	基础库 3.x
`latitude`	✅	✅
`longitude`	✅	✅
`accuracy`	✅	✅
`altitude`	部分支持	✅
`verticalAccuracy`	❌	✅
`horizontalAccuracy`	❌	✅
`speed`	部分支持	✅

工具的 current-location 页调一次就把当前基础库的完整字段落进 history——下次切基础库再调一次，直接对比历史记录里的字段差异。这种活之前只能靠记忆或者多截图，现在工具自动给你留底。

设计上的克制（为什么不做”更多功能”）

我做这个工具时刻意控制了三件事，因为联调场景最怕工具自作主张：

1. 不加工微信回调数据

弹窗里看到的 success 回调，就是 wx.login 真实返回的对象——不增加字段、不重命名、不混入输入参数或调用时间戳。后端同事拿到的物料，就是微信原始返回，没有任何解读成本。

2. 调用历史只存本地

history-store.js 用 wx.setStorageSync 存最近 50 条，不上传任何服务器。联调数据可能含敏感 code、令牌、定位坐标——存本地用完清空，比传到”云端调试平台”安全得多。

const HISTORY_KEY = 'api_debug_history'
const MAX_HISTORY = 50

function add({ api, outcome, data }) {
  const history = read()
  const record = { id: createId(), api, outcome, createdAt: Date.now(), data }
  wx.setStorageSync(HISTORY_KEY, [record, ...history].slice(0, MAX_HISTORY))
  return record
}

写入即截断，没有清理逻辑就不会泄漏。

3. 不实现后端能力

code2Session、手机号换取、订阅消息下发——这些都在后端领域。我故意不在工具里写后端逻辑，让前后端边界保持清晰。

技术架构（给想二次开发的人）

维度	选型	为什么
框架	微信原生	不需要 Taro/uni-app 的转译层，调试工具越接近原生越好
UI	Vant Weapp `^1.11.7`	移动端组件库成熟，源码直接放 `miniprogram/components/vant/` 避免 npm 构建抽风
Node	18+	仅用于检查脚本
存储	`wx.setStorageSync`	无后端、无依赖
配置	占位 AppID + `project.private.config.json`	仓库可公开，AppID 留在本地

14 个页面，对应 4 类能力：

能力域	页面
登录与身份	`login` / `phone`
位置与地图	`current-location` / `choose-location` / `open-location` / `location`（总览）
订阅消息	`subscribe`
权限与环境	`auth` / `permissions` / `environment`
工具	`clipboard` / `history` / `settings`

快速上手

git clone https://github.com/wlxweb/wechat-api-debug-miniapp.git
cd wechat-api-debug-miniapp

npm install --prefix miniprogram

# 微信开发者工具 → 导入项目
#   - 目录：仓库根目录
#   - AppID：你自己的
#   - 小程序目录：miniprogram/

# 可选：提交前自检（含凭证扫描）
npm run check

第一次跑记得在「详情 → 本地设置」勾上不校验合法域名——这选项只对本地调试生效，真机 / 体验版 / 正式版依然要走微信侧规则。

我自己怎么用

说点具体的：

新接一个项目，第一步是导入这个工具，测一遍 wx.login 和 wx.getLocation，把回调 JSON 发给后端，省掉第一次对接的来回
跨小程序复用：同时维护几个 AppID，每个都要测一遍订阅消息，工具里换模板 ID 就行，不用写新 demo
给新人演示：新同事不知道微信回调长啥样，工具弹窗给他看一眼就懂
问题复盘：线上遇到诡异的回调，工具里能复现同样基础库下的回调结构