小程序 Sentry 没有数据?错误上报排查
小程序初始化 Sentry 后没有数据,先主动发送一个测试错误,再检查 DSN、合法域名、初始化顺序和发送条件。 有 event ID 或 flush() 成功仍需在正确的 Sentry 项目里找到事件;只缺组件错误时,另查 React / Vue 错误处理。
| 你看到的现象 | 从这里开始 |
|---|---|
| 初始化后完全没有错误数据 | 最小上报链路与检查清单 |
| 全局错误有数据,Vue / React 组件错误没有 | 组件错误捕获 |
已有事件,但只显示压缩代码或 appservice.app.js | Source Map 排障 |
| 需要用户同意后才能发送监控数据 | 隐私同意配置 |
首次接入可按原生小程序、Taro或 uni-app指南完成配置。
初始化后 Sentry 里没有数据,先查什么?
先用最小链路确认 SDK 是否能发出事件:
Sentry.captureException(new Error('sentry test'));如果 Sentry Issues 里仍然看不到事件,按这个顺序排查:
- DSN / Project 是否可用:确认 DSN 属于当前要看的 Sentry Project,且没有把测试事件发到其它环境或其它项目里。
- request 合法域名是否配置:核对实际运行的 AppID 和实际上报地址,按快速接入的域名检查填写完整域名;配置
tunnel时检查 tunnel 地址。关闭手机调试和开发者工具的「不校验合法域名」后再验收。 - 初始化位置是否太晚:应在
App()之前初始化;放进App.onLaunch无法补回已经发生的启动异常或本次onLaunch面包屑。原生前台与后台监听均可用时,仍可管理初始化后的 Session;用getDiagnostics()检查生命周期警告,详见初始化时序。 - 是否只调用了
addBreadcrumb:面包屑不会单独上报,只会随下一次 error / message 事件一起发送(性能 span 使用属性,不携带错误事件的面包屑)。验证接入时请用captureException或captureMessage。 - 是否启用并获得发送同意:检查
Sentry.isEnabled();配置requireConsent: true时,还要检查Sentry.getConsent()。启用 SDK 和允许发送是两个独立条件。 - 事件是否被过滤或采样:检查
sampleRate、ignoreErrors、beforeSend以及 Sentry 页面的时间、环境和搜索条件。验证性能 span 时,另查tracesSampleRate/tracesSampler和ignoreSpans。 - 开发者工具与真机差异:微信开发者工具某些环境的报错不触发底层
wx.onError,建议用真机预览验证自动异常捕获。 - 框架是否已经处理组件错误:uni-app / Taro 的组件错误可能被 Vue / React 先接住,不一定冒泡到平台全局
onError。这类错误需要接框架错误处理,见 组件内错误。
排查时也可以打印诊断信息,并把输出贴到 GitHub issue:
console.log(Sentry.getDiagnostics());有 event ID 或 flush 成功,就表示后台收到了吗?
event ID 表示发起了采集,不证明事件通过过滤、采样和网络发送。flush() 返回 true 表示本次等待按 SDK 语义完成;事件仍可能在同意缓存中,或被服务端过滤。
验收时,先检查实际请求结果,再用 event ID 在正确项目和环境中找到事件。Source Map 还要单独确认源码文件、行列号和上下文,见 Source Map 验证。
init() 返回 undefined,宿主就绪后能重试吗?
2.3.1 起可以。 如果首次调用时还没有可读的微信、支付宝、字节跳动、钉钉、QQ、百度或快手宿主对象,SDK 不会创建实例,也不会永久缓存探测失败;宿主可用后,在应用持久入口显式重新调用 Sentry.init(options) 即可,不需要重载模块或调用内部重置函数。提前调用诊断或平台探测也不会阻止后续恢复。较旧版本应先按升级说明更新 SDK。
SDK 不会在后台轮询,也不会补采初始化之前的异常、请求或生命周期。成功识别后会继续使用该宿主,重复初始化不用于动态切换平台。若宿主一直缺失,请确认构建目标;H5 应使用官方浏览器 SDK。undefined 也可能来自临时 withScope/异步 span 中初始化或采集回调同步重入,须按初始化与切换约束排查,不能通过循环重试绕过。
初始化后必须在 onError 中手动调 API 吗?
不需要重复上报。 SDK 注册宿主可用的全局异常监听。尽早初始化以覆盖启动阶段;缺少监听 API 时,业务仍可主动调用捕获方法。
如果整体没有数据,先按 初始化后没有数据 的清单排查;如果只有组件内错误缺失,继续看 组件内错误。
网络请求会随错误事件一起上报吗?
会,且默认开启。 SDK 默认启用 NetworkBreadcrumbs,包装宿主请求 API(如 wx.request / my.httpRequest),把每个网络请求记成 category: xhr 的面包屑,随下一个被捕获的错误事件一起上报(与 @sentry/browser 默认行为一致)。
- 默认字段:
url(只到路径)/url.query(按dataCollection.urlQueryParams过滤)/method/status_code/duration;请求进入宿主fail回调时标error级,进入success回调但 HTTP 状态为 4xx/5xx 时标warning级,慢请求(>3s)也标warning级。 - 默认不带请求 / 响应体,需要 body 时开启
traceNetworkBody: true:体先按敏感键片段脱敏(core 内置名单 + 本 SDK 的支付/证件片段,可用顶层sensitiveKeys追加),再按maxRequestBodySize(默认 1 MB)截断;按 URL 排除仍可在beforeBreadcrumb里二次处理。 - uni-app / Taro 无需额外配置:
uni.request/Taro.request最终会走到对应小程序端被包裹的全局请求 API(如微信wx.request、支付宝my.httpRequest)。
如果错误里没有网络面包屑,多半是:① 错误触发前没发过请求;② Sentry.init 晚于请求执行(务必在请求之前 init)。
Sentry.logger.* 和 console 面包屑有什么区别?
Sentry.logger.* 发送独立业务日志,用于查询、聚合和告警;用 beforeSendLog 过滤。
enableConsoleBreadcrumbs 只会把 console.log/warn/error 记录成面包屑,随下一次 error / message 事件一起发送;如果后续没有事件,它不会单独出现在 Sentry。
组件内错误
uni-app(Vue)组件内的错误没上报 / 上报率很低?
uni-app 底层是 Vue。组件渲染、生命周期、watch 或模板事件中的异常可能先被 Vue errorHandler 接住,不再冒泡到平台 onError。Vue 3 需要接 app.config.errorHandler,Vue 2 使用 Vue.config.errorHandler。完整代码只在 uni-app 接入指南维护。
Taro 呢?
Taro React 的渲染、构造函数和生命周期错误建议由 Error Boundary 捕获并转交 Sentry;事件回调和异步错误不属于 Error Boundary 的捕获范围。使用 Taro Vue 时按 Vue errorHandler 处理。完整代码见 Taro 接入指南。
隐私协议同意前如何避免发送 Sentry 网络请求?
默认情况下,SDK 会按初始化配置正常上报。如果业务要求用户同意隐私协议前不能发出 Sentry 网络请求,初始化时设置 requireConsent: true,用户明确同意后调用 Sentry.setConsent(true)。
Sentry.init({
dsn: 'YOUR_DSN', // 替换为 Sentry 项目中的完整 DSN
requireConsent: true,
});
// 用户明确同意隐私协议后
Sentry.setConsent(true);同意前事件会写入本地缓冲;放行后会补发并恢复实时上报。撤回同意、缓存上限和验证方法见可靠上报与隐私同意。如果只是想降低上报量,请使用采样配置,不要把 consent 当作采样开关。
支持 Session Replay(屏幕操作回放)吗?
sentry-miniapp 2.1.0 或更新版本提供可选的实验性微信页面回放,通过公开节点 API 采样明确标记区域的布局、文本变化与点击,并关联 Sentry 错误。它需要安装回放集成并生成模板标记,不能完整复现未标记内容或原生绘制;其它平台、小游戏和 Skyline 跳过。Sentry 官方浏览器录制器仍不能直接装入小程序逻辑层。
uni-app / Taro 的 H5 端如何监控?
sentry-miniapp 仅适配小程序平台,不内置浏览器原生信号(window.onerror、fetch/XHR 拦截等)。H5 端请用官方 @sentry/browser,按端条件编译引入;两端上报同一个 DSN 即可在同一 Project 聚合查看。
条件编译的具体写法见 Taro 接入指南 与 uni-app 接入指南 的「分端接入」一节。
