我把 Sentry 接进了 7 端小程序：从异常捕获、Breadcrumb 到 Source Map 定位

微信、支付宝、字节、百度、QQ、钉钉、快手 7 端小程序，一套代码统一接入 Sentry，把异常捕获、用户路径、弱网兜底、Source Map 定位真正串成一套可落地的工程方案。

很多团队不是不想做小程序监控，而是试了一圈之后发现：

• 官方能力能解决一部分问题，但很难覆盖多端统一治理
• Web 监控 SDK 不能直接塞进小程序环境
• 错误即使上报了，没有 Source Map 和上下文也依然难排查
• 真正接入时，还会遇到域名白名单、弱网、堆栈路径不一致这些工程问题

这篇文章不讲抽象概念，直接回答一个更实际的问题：

如果你想把小程序真正接进 Sentry，这件事应该怎么落地？

一、为什么小程序线上问题比 Web 更难排查？

做过小程序开发的人，大概率都见过这些场景：

• 用户说“页面打不开了”，但你在开发者工具里怎么都复现不出来
• 某个 API 只在低版本基础库报错，测试同学根本测不到
• 某个请求偶发超时，最终在业务里表现成“按钮点了没反应”
• 某个版本上线后投诉变多，但你不知道到底是哪个页面、哪个操作、哪类设备在出问题

Web 端出了问题，大家已经习惯去看 Sentry、日志平台、APM。

但到了小程序，事情一下变复杂了：

• 不是标准浏览器环境
• 没有 DOM
• 各平台运行时不一致
• 上报链路受域名白名单和网络环境影响
• 堆栈路径不是标准 URL，Source Map 解析也更麻烦

这就导致一个很现实的问题：

很多团队并不是没有监控意识，而是缺少一套真正适合小程序环境的工程化方案。

二、只靠微信官方能力，够不够？

先说结论：

• 如果你只做微信单端项目，官方能力通常已经够用
• 如果你做的是多端小程序，或者已经在用 Sentry 监控 Web / App / Backend，那么官方能力通常不够

微信官方已经提供了不少能力：

• wx.getRealtimeLogManager() 实时日志
• We 分析里的 JS 错误分析
• Source Map 能力
• 开发者工具的性能分析
• 真机调试

这些能力对于单微信项目非常有价值。

但一旦进入下面这些场景，就会明显吃力：

• 同时维护微信、支付宝、字节等多个小程序端
• 希望把小程序纳入现有 Sentry 体系
• 希望看到页面跳转、请求、用户动作形成的完整上下文
• 希望弱网/断网时错误上报尽量不丢
• 希望前后端链路能串起来

这时候问题就不再是“有没有监控”，而是：

能不能有一套跨平台、可统一治理、能真正接进研发流程的监控方案。

三、为什么不能直接把 Web SDK 搬进来？

这是很多人第一反应会踩的坑。

Sentry 官方 JavaScript SDK 很强，但小程序和 Web 有几个本质差异：

• 小程序没有浏览器 DOM 与标准事件系统
• 小程序网络请求不是 fetch / XMLHttpRequest
• 各平台全局对象、生命周期、错误入口都不一样
• 运行时堆栈路径往往是虚拟路径，不适合直接做 Source Map 匹配

所以如果要让 Sentry 真正在小程序里落地，需要额外做几件事：

• 抹平多端运行时 API 差异
• 接管小程序特有的错误与生命周期
• 用小程序 request 定制 Transport
• 处理弱网场景下的离线缓存与重试
• 对堆栈路径做归一化，方便 Source Map 还原

这也是我做 sentry-miniapp 的原因。

四、sentry-miniapp 到底解决了什么问题？

sentry-miniapp 是一个基于 @sentry/core 构建的多端小程序监控 SDK。

它要解决的不是“监控平台从 0 到 1 重做一遍”，而是：

让小程序团队也能获得接近现代 Web 工程的错误监控与排查体验。

当前覆盖的平台包括：

• 微信小程序
• 支付宝小程序
• 字节跳动 / 抖音小程序
• 百度小程序
• QQ 小程序
• 钉钉小程序
• 快手小程序

同时也兼容：

• Taro
• uni-app

换句话说，它补的是“小程序环境里的最后一公里适配”。

五、它具体能做什么？

核心能力包括：

• 自动捕获未处理异常与 Promise rejection
• 记录页面跳转、网络请求、用户动作等 Breadcrumb
• 采集设备、系统、基础库等环境信息
• 支持多端路径归一化，配合 Source Map 定位源码
• 支持弱网 / 断网场景下的离线缓存
• 支持把小程序纳入现有 Sentry 项目与 release 流程

如果你已经在用 Sentry，最直接的价值就是：

小程序终于不再是监控体系里的孤岛。

下面这张图可以直观看到，事件进入 Sentry 后，不再只是零散日志，而是形成了可检索、可聚合的问题列表：

六、5 分钟接入一个最小示例

1. 安装

npm install sentry-miniapp

2. 初始化

在 app.js 或 app.ts 中，放在 App() 调用之前：

const Sentry = require('sentry-miniapp');

Sentry.init({
  dsn: 'https://your-key@sentry.io/your-project-id',
  release: 'my-miniapp@1.0.0',
  environment: 'production',
});

App({
  // 你的 App 配置
});

完成初始化后，SDK 会自动做几件事：

• 捕获未处理异常
• 记录基础上下文
• 接入请求链路
• 为后续排查保留设备与运行时信息

3. 给关键业务补上下文

真正有价值的监控，不是只有一条 error message，而是能把错误和业务动作关联起来。

try {
  riskyOperation();
} catch (error) {
  Sentry.captureException(error);
}

Sentry.captureMessage('用户完成首次支付', 'info');

Sentry.setUser({ id: 'user123', username: '张三' });
Sentry.setTag('page', 'payment');
Sentry.setContext('order', { orderId: '2024001', amount: 99.9 });

这样当线上真的出问题时，你看到的不只是“报错了”，而是：

• 哪个用户
• 在哪个页面
• 做了什么操作
• 哪个订单上下文下出的错

实际落到后台时，错误详情会把堆栈、上下文、标签、用户信息集中展示，排查效率会比“用户口头反馈 + 本地猜测”高很多：

七、真正决定排查体验的，是 Source Map

很多团队其实不是没有上报，而是上报之后看不懂。

原因通常有三个：

• 线上代码经过压缩
• 小程序运行时堆栈路径和源码路径不一致
• release 与 sourcemap 没有严格对齐

如果不把这件事打通，监控平台的体验会大打折扣。

上传 sourcemap 的方式可以是：

sentry-cli releases files "my-miniapp@1.0.0" upload-sourcemaps ./dist \
  --url-prefix "app:///" \
  --ext js --ext map

这里最关键的，不只是命令本身，而是两件事：

• 堆栈路径要能被统一映射
• 构建产物必须和 release 版本严格对应

sentry-miniapp 做的一件重要事情，就是把不同平台的虚拟路径统一处理到 app:/// 语义下，降低小程序 Source Map 对齐的复杂度。

当 Source Map 对齐之后，后台里看到的异常详情就不再只是“压缩后看不懂的堆栈”，而是可以真正用于定位源码的问题信息：

八、这套方案真正带来的收益是什么？

如果接入完整，它带来的不只是“多一个报错工具”，而是四层收益。

1. 从“知道报错”到“知道用户怎么走到这里”

你能看到页面路径、用户动作、请求链路，而不是孤零零一条异常。

这也是为什么 Breadcrumb 对线上排查特别重要：错误并不是孤立发生的，它往往是前面一连串操作和请求共同导致的。

2. 从“单端排查”到“多端统一治理”

如果你的业务同时跑在多个小程序端，一个统一面板带来的收益非常大。

3. 从“只能复现”到“即使复现不了也能定位”

很多线上问题压根难以稳定复现，真正有价值的是：

基于上下文快速缩小排查范围。

4. 从“一个 SDK”到“纳入版本与研发流程”

一旦和 release、Source Map、CI/CD 结合起来，监控才会真正变成工程资产，而不是可有可无的埋点。

如果再把性能链路一起接进来，后台看到的就不只是“错误发生了”，还包括请求与资源加载的上下游关系，这对排查慢请求、偶发超时、页面卡顿尤其有帮助：

九、什么团队最适合上这套方案？

更适合下面这些团队：

• 多端小程序团队
• 已经在用 Sentry 的团队
• 对发布质量、错误治理有明确要求的团队
• 线上问题定位成本高、业务链路复杂的团队

如果你只是一个微信单端、规模不大、诉求不复杂的小程序项目，优先把官方能力用扎实，通常会更划算。

十、更务实的接入建议：分三层做，不要一步到位

如果让我给建议，我会这么分层：

• 第一层：先把微信官方能力用好
• 第二层：出现多端、统一治理、跨系统追踪需求时，再补统一监控方案
• 第三层：把 release、Source Map、告警、回归分析接进 CI/CD

这样不会一上来就引入太多复杂度，但每一步都能产生明确收益。

十一、项目地址

如果你正好在做下面这些事情，可以看看这个项目：

• GitHub: github.com/lizhiyao/se…
• npm: npmjs.com/package/sen…

它适合的不是所有小程序项目，而是这些场景：

• 多端统一监控
• 接入现有 Sentry 体系
• 处理小程序环境下的 Source Map、弱网缓存、跨端 API 差异

十二、结语

小程序监控这件事，真正难的不是“把错误发出去”，而是：

• 能不能在小程序环境里稳定发出去
• 能不能带着足够多的上下文发出去
• 能不能最终定位到源码
• 能不能接进团队已有的研发流程

如果这些都做到了，小程序监控就不再只是“补日志”，而是真正开始具备工程价值。

如果你已经在用 Sentry，或者正在考虑给多端小程序补一套统一监控链路，这个项目也许正好能帮你少踩很多坑：

• GitHub: github.com/lizhiyao/se…
• npm: npmjs.com/package/sen…