微信小程序 Sentry Source Map 排障与两层映射
Source Map 上传成功但堆栈仍是压缩代码,先核对事件与上传产物是否来自同一次构建。 release、运行文件名和映射关系都要对应;微信真机出现 appservice.app.js 时,分页 map 可能不足以还原,需要检查微信外层映射是否还要与框架 map 合成。
本页从事件中的表现选择排查路径,覆盖微信小程序、其它平台、Cocos 小游戏和 Debug ID。Taro / uni-app 的初始化与组件错误捕获见 Taro 接入 / uni-app 接入。尚未完成基础配置时,先按 Source Map 上线指南生成、上传并验证一组 .js + .map。
本地 Source Map Doctor
包内提供静态体检命令。先按快速接入安装 SDK,再在业务项目中运行以下命令;--no-install 使用本项目的 SDK,避免临时下载另一个版本。Doctor 不会登录 Sentry、上传或修改文件,只检查本地产物是否具备上传条件。
npx --no-install sentry-miniapp-sourcemap-doctor \
--dist ./dist \
--release "my-miniapp@1.0.0"Doctor 会检查:
- 构建目录是否同时存在运行时
.js和.map; sourceMappingURL是否断链,或是否为合理的 hidden source map;- map 是否为合法 JSON,是否包含
sources、mappings和完整sourcesContent; - 按实际 JS 相对上传目录与
--url-prefix推导的 artifact 是否符合默认app:///路径;不会用 map 的file字段覆盖目录结构; - 是否提供 release,并提醒与
Sentry.init({ release })保持一致。
CI 中建议开启严格模式:
npx --no-install sentry-miniapp-sourcemap-doctor \
--dist ./dist \
--release "$SENTRY_RELEASE" \
--strict提交 Issue 或为 CI 留档时可加 --json。Doctor 默认忽略 .d.ts.map,只检查需要上传的运行时 artifact。
先按现象选择排查路径
| 事件中的表现 | 优先检查 |
|---|---|
filename 是分页文件,但显示压缩代码 | release、artifact 名称、JS/map 是否成对、sourcesContent |
filename 是 app:///appservice.app.js 或 app:///app-service.js | 微信真机两层 Source Map |
filename 是 app:///game.js,坐标无法用同版本 Cocos map 还原 | 微信小游戏 / Cocos Creator 两层映射排查 |
filename 使用 chunks://、assets/ 或私有协议 | 平台路径与上传 artifact 结构 |
事件有 debug_meta 但仍未解析 | Debug ID 是否注入到最终发布的 JS、对应 bundle 是否上传 |
| 堆栈本身就缺少 filename / 行列 | 自定义 stackParser 或运行时堆栈能力 |
平台路径差异
微信小程序
尽量让 Webpack / Vite 完成转译和压缩,并关闭微信开发者工具中会再次改变 JS 行列号的编译选项。SDK 会剥离 appservice/、app-service/ 和 WAService/ 等虚拟前缀。
真机可能把逻辑层合并为 appservice.app.js 或 app-service.js。这不是路径前缀问题,需按下一节处理;上传名称以实际事件堆栈为准。
支付宝、字节、百度与其它平台
- 支付宝的
https://appx/会归一为app:///; - 字节小程序 / 抖音小游戏的
tt://会被剥离; - 百度的
swan://会被剥离; - QQ、钉钉、快手等协议前缀也会归一化。
抖音小游戏接入 Cocos 时,chunks:///_virtual/foo.js 和 chunks:///assets/foo.js 会分别变成 app:///chunks/_virtual/foo.js 与 app:///chunks/assets/foo.js。上传目录也要保留相同的 chunks/... 相对路径。
微信真机的两层 Source Map
Taro / uni-app 项目在微信真机上常见这样的堆栈:
app:///appservice.app.js:123456:78框架构建产物却是 app.js、vendors.js 和 pages/*/index.js。此时上传分页 map 无法解析,因为真机执行文件与上传 artifact 根本不是同一个文件。
为什么有两层
源码 .vue / .tsx
↓ 框架构建 Map A
分页编译产物 JS
↓ 微信合并与转译 Map B
appservice.app.js- 只上传 Map A:能描述分页 JS 到源码,但匹配不到
appservice.app.js; - 如果 Map B 的
sources仍指向分页编译产物,就需要与 Map A 离线合成,才能继续到.vue/.tsx; - 如果 Map B 已包含原始源码及
sourcesContent,先用实际事件坐标验证映射,不必重复合成。微信编译结果可能已经保留上传前 JS 的内嵌映射。
1. 获取并检查最终 map
- Map B:从微信“ We 分析 → 性能 / JS 报错 → 下载线上 Source Map”获取与体验版或线上版完全一致的
appservice.app.js.map; - Map A:在 Taro / uni-app 构建中开启 Source Map,保留所有分页构建 map;Map B 尚未映射到原始源码时,再用它们合成。
开发预览的 map 不能替代线上版本,外层 map 必须与实际发布构建一致。使用 miniprogram-ci getDevSourceMap 下载开发版映射时,上传与下载必须使用同一 robot;它返回该 robot 最近上传版本的映射,不能拿另一个机器人或开发者工具上传的版本混用。命令参数见 miniprogram-ci 文档。
2. 需要合成时,先检查能否匹配
npx --no-install sentry-miniapp-sourcemap-doctor \
--wechat ./wechat/appservice.app.js.map \
--build-maps ./dist/dev/mp-weixin \
--strip webpack:// \
--release "$SENTRY_RELEASE"结果会列出 matched、unmatched 和 ambiguous。文件名对不齐时,按输出调整 --strip 或构建产物路径。
3. 需要合成时,生成最终 map
合成工具需要业务项目的开发依赖 source-map,不增加小程序运行时依赖。安装后使用同一 SDK 包提供的命令:
npm install --save-dev source-map
npx --no-install sentry-miniapp-sourcemap-merge \
--wechat ./wechat/appservice.app.js.map \
--build-maps ./dist/dev/mp-weixin \
--out ./merged/appservice.app.js.map \
--strip webpack://脚本优先按相对路径精确匹配,最后才按文件名兜底。多个页面都叫 index.js 时会标记歧义并跳过,避免静默套错 map。
4. 上传并验证
把最终 map 与对应的运行 JS 成对上传,文件名以实际事件为准:例如 app:///appservice.app.js 或 app:///app-service.js。map 的 file 字段可能为空,不能只靠这个字段判断运行文件名。
下载得到 .map 不代表已经具备完整上传条件。先检查同版本编译产物是否包含事件所指的运行 JS;getCompiledResult 导出的上传包可能仍是 app.js、pages/*/*.js 等分页文件,不能把其中任意文件改名为 app-service.js 来配对。缺少最终运行 JS 时,可先用 map 检查本地坐标,但仍须取得与事件对应的 JS,才能完成成对上传和后台验证。
上传完成后新触发一个真机错误,核对 release、运行文件名与行列,再确认后台堆栈及源码上下文。
合成精度取两份 map 中较低的一层;个别列号可能不精确。该方案属于 best-effort,匹配效果取决于框架、打包器和版本产生的 source 名称。
相关背景见 issue #162 与 issue #173。
微信小游戏 / Cocos Creator 两层映射
Cocos Creator 生成的 game.js.map 通常描述 Cocos 构建的 game.js → TypeScript 源码。如果真机执行的 app:///game.js 能直接用这份 map 还原,就不需要本节。
只有同时出现以下情况时,才继续检查两层映射:
- 体验版或正式版事件的
filename是app:///game.js; - 事件行列号无法用同一次 Cocos 构建的
game.js.map还原; - 微信上传启用了 ES6 转 ES5、JS 压缩或代码保护等可能改写 JS 的选项。
这些现象只能说明“上传前后产物可能不同”,不能只凭两个行号直接认定根因。先确认事件的 mechanism、release 中是否同时存在 app:///game.js 与 app:///game.js.map,并确保所有文件来自同一次上传。
1. 准备同版本文件
| 文件 | 映射关系 | 获取方式 |
|---|---|---|
微信上传包中的 game.js | Sentry 中的 app:///game.js artifact | 在同一上传流水线中保存编译结果;miniprogram-ci get-compiled-result 可导出本地编译后的上传包 |
微信外层 game.js.map(Map B) | 微信上传包 game.js → 上传前 game.js | 从 WE 分析下载,或用 miniprogram-ci get-dev-source-map 获取同一 robot 最近上传版本 |
Cocos game.js.map(Map A) | 上传前 game.js → .ts 源码 | Cocos Creator 同一次构建生成 |
get-compiled-result 会重新编译当前本地项目,不能代替已经丢失的历史线上产物。建议在上传流水线中保存它,并确保项目、编译设置、robot 与实际发布版本一致。微信的命令和参数以 miniprogram-ci 文档为准。
2. 诊断两层 map 是否能对齐
把两份同名 map 分开放置,再运行:
npx --no-install sentry-miniapp-sourcemap-doctor \
--wechat ./maps/wechat-online/game.js.map \
--build-maps ./maps/cocos-build \
--release "$SENTRY_RELEASE"只有输出中的 matched 大于 0,才继续合成。unmatched 或 ambiguous 表示外层 map 的 source 名称还无法唯一对应到 Cocos 构建 map。
3. 合成并上传
先安装开发依赖 source-map 和 sentry-cli,再运行:
npx --no-install sentry-miniapp-sourcemap-merge \
--wechat ./maps/wechat-online/game.js.map \
--build-maps ./maps/cocos-build \
--out ./sentry-upload/game.js.map
npx --no-install sentry-cli sourcemaps upload --release "$SENTRY_RELEASE" ./sentry-upload \
--url-prefix "app:///" \
--ext js \
--ext map \
--validate上传目录中还要放入同一微信上传版本的 game.js。SDK 的 release 必须与 $SENTRY_RELEASE 完全一致;上传后触发一个新事件验证,旧事件不会被重新处理。
这个流程是可验证的 best-effort 工具链,不承诺所有 Cocos / 微信版本的 source 名称都能自动匹配。doctor 无法匹配时应保留诊断结果并补充脱敏样本,不要强行合成。
Debug ID 与自定义 stackParser
使用构建插件注入 Debug ID 时,上传和部署须使用同一份注入后的 JS 与 map。SDK 负责把宿主可见的 Debug ID 交给 Sentry;仍应核对新事件的 debug_meta 与上传文件的 ID。额外的微信编译可能改变代码和映射,需要按前面的两层映射流程检查。
Debug ID 与 release + 路径是不同的匹配依据。使用 Debug ID 时,不能仅凭 release 相同判断匹配成功;使用本页的 release 上传命令时,也不能仅凭注入代码存在判断匹配成功。先确认本次上传和事件实际具备哪种匹配信息,详见 Sentry 官方排障说明。
大多数项目无需设置 stackParser。内置 miniappStackParser 已覆盖常见 V8、Safari、JavaScriptCore 以及小程序虚拟路径格式。
只有私有引擎、特殊打包器或非标准堆栈无法解析时才覆盖:
import * as Sentry from 'sentry-miniapp';
Sentry.init({
dsn: 'YOUR_DSN',
release: 'my-game@1.0.0',
stackParser: (stack, skipFirstLines, framesToPop) => {
// 可先委托默认解析器,再按私有格式补充或修正 StackFrame。
return Sentry.miniappStackParser(stack, skipFirstLines, framesToPop);
},
});stackParser 只负责把运行时字符串解析成 StackFrame,不会生成或上传 Source Map,也不会放宽 release / artifact 匹配要求。
上传成功仍无法还原
按这个顺序检查,通常比反复重传更快:
- 在新事件原始 JSON 中确认 release、
filename、行号和列号。 - 在 Sentry 项目 Source Maps/artifact bundle 页面检查上传记录、文件名与 Debug ID。
- 确认上传的是同一次生产构建生成的 JS 与 map,并包含
sourcesContent。 - 检查
filename是否为appservice.app.js,避免拿分页 map 匹配合并文件。 - 使用事件详情的 Unminify Code/Source Map Debug 检查未匹配原因。
- 上传完成后重新触发事件;Sentry 不会回溯处理旧事件。
- 自托管 Sentry 还需检查 symbolicator、worker 与 artifact 存储是否正常。
CI 上传失败
确认 Token 权限、SENTRY_ORG、SENTRY_PROJECT、自托管地址和网络连通性。Source Map 很大时检查 CLI 超时配置,并确认产物没有被预先 gzip。
安全要求
- Auth Token 只放在 CI Secret 或未入库的本地配置中;
- 上传完成后删除
.map,不要打进小程序包或公开托管; - 合成 map 内含
sourcesContent,同样只能用于上传; - 先上传 artifact,再发布对应构建,避免事件先于 map 到达 Sentry。
仍无法定位时,提交 Issue 时附 SDK 版本、平台、框架、事件 filename、release、Doctor JSON 输出和脱敏后的 Sentry.getDiagnostics()。
