Sentry Miniapp SDK — 小程序监控 SDK

简体中文 | English

一个基于 @sentry/core 核心构建的小程序监控 SDK，提供异常监控、性能监控、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序，以及微信 / 抖音等小游戏，并兼容 Taro / uni-app 等跨端框架。

📖 完整文档请看文档站：sentry-miniapp.pages.dev —— 快速接入、能力矩阵、各框架接入、FAQ、Source Map 配置、示例索引，带导航与搜索。本 README 只做速览与入口。

📰 最新文章：《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》 — sentry-miniapp 已被收录进 Sentry 官方文档的 community-supported SDK 列表。觉得有用请帮忙点个 ⭐ Star，让更多小程序团队找到它。

| 版本 | 亮点 | |---|---| | v1.11 | 小游戏性能数据独立上报为 transaction（进 Sentry Performance 页）；API 请求上报为 http.client span；上线文档站、新增 Taro / uni-app 集成示例与两层 Source Map 离线合成脚本 | | v1.10 | 🎮 小游戏支持：自动识别小游戏环境，新增冷启动首帧耗时、帧率 / 卡顿（FPS / jank）监控 | | v1.8.0 | AI 辅助接入 skill — Claude Code / Cursor 自动引导集成 | | v1.7.0 | 新增 tracesSampler 动态采样；新增 Source Map 完整配置指南 | | v1.6.0 | 13 项功能优化 + 16 项问题修复；构建产物压缩，包体积减少约 59% | | v1.5.0 | Performance 增强（可配阈值 / setData 慢渲染检测 / 内存采集）；新增页面生命周期、用户交互、Console 三类 Breadcrumb | | v1.4.0 | NetworkBreadcrumbs 抓 Request / Response Body；离线缓存上限可配 | | v1.3.0 | 🎯 重构构建（Vite + bundle-inline）：对外零依赖，修掉 miniprogram_npm 模块解析问题；内置 Source Map 路径自动抹平 |

完整变更见 CHANGELOG.md。

✨ 核心特性

• 🚀 现代架构：基于 Sentry JavaScript V10 SDK 核心模块构建。
• 📱 真正的多端支持：内置 API 抹平引擎，一套代码兼容微信、支付宝、字节、百度、QQ、钉钉、快手等主流小程序平台。
• 🎮 小游戏支持：自动识别小游戏环境，异常 / 网络 / 设备监控开箱即用，并提供小游戏专属的冷启动首帧耗时与帧率 / 卡顿监控。
• 🎯 全自动异常捕获：无需侵入业务代码，自动监听并上报生命周期异常（onError、onUnhandledRejection、onPageNotFound、onMemoryWarning）。
• 🍞 丰富的上下文面包屑：自动记录设备信息、用户点击 / 触摸、网络请求（XHR）以及页面生命周期。
• 🗺️ 内置 SourceMap 路径抹平：自动统一多端虚拟堆栈路径，配合 sentry-cli 极简实现 Source Map 解析。
• 📡 弱网离线缓存：断网或发送失败时自动缓存事件到本地 Storage，网络恢复后静默重试，确保数据不丢失。
• ⚡ 深度性能监控：采集导航性能（FCP/LCP）、渲染性能、资源加载耗时及自定义性能标记。
• 🔗 分布式追踪：自动注入 sentry-trace / baggage 头，并将 API 请求耗时上报为 http.client span，串联小程序与后端调用链。
• 📊 Session 健康监控 与 📶 网络状态监控：会话生命周期管理 + 实时网络变化追踪（WiFi/4G/离线）。
• 🛡️ 智能降噪：内置错误去重与采样率控制，避免日志风暴。

📦 安装

npm install sentry-miniapp

不使用 npm 时，也可直接将 examples/wxapp/lib/sentry-miniapp.js 复制到小程序项目中引入。

🤖 AI 辅助接入

使用 Claude Code 或 Cursor 时，可让 AI 自动引导接入：

npx skills add https://github.com/lizhiyao/sentry-miniapp --skill sentry-miniapp-sdk

安装后在 AI 编辑器中输入“帮我接入 Sentry 监控”即可触发向导。

🚀 快速接入

前置：① 准备一个 Sentry 账号（官方 SaaS 或私有化部署）；② 在小程序后台把 Sentry 上报域名加入 request 合法域名。

在入口文件（app.js / app.ts）最顶部、App() 之前初始化：

import * as Sentry from 'sentry-miniapp';

Sentry.init({
  dsn: 'https://<key>@sentry.io/<project>',
  release: '[email protected]', // 与上传 Source Map 时的 release 一致
  environment: 'production',
  sampleRate: 1.0, // 异常采样率
  tracesSampleRate: 1.0, // 性能采样率；开启后 API 请求作为 http.client span 上报
});

App({ onLaunch() {} });

不要把 Sentry.init 放进 App.onLaunch 里：那时 App() 已经完成注册，SDK 无法再提前包装本次 onLaunch，因此 App 生命周期面包屑、Session 首次启动以及依赖 onLaunch 起点的冷启动耗时可能拿不到。若只关心后续异常、网络面包屑和手动上报，放在 onLaunch 内仍可工作，但启动阶段能力会降级。

默认集成已含异常捕获、性能监控、Source Map 路径归一化、网络面包屑、Session 与网络状态监控，通常无需手动传 integrations（传入会覆盖默认）。完整配置项（离线缓存、追踪头注入、面包屑开关等）见文档站 · 配置项参考。

验证是否打通——主动捕获一个事件，到 Sentry「Issues」列表查看：

Sentry.captureException(new Error('sentry test'));

⚠️ addBreadcrumb 不会单独上报，只随下一次事件一起发送——只调它而不捕获事件，后台会一直没有数据。

📚 常用 API

// 手动捕获异常 / 消息
Sentry.captureException(new Error('支付接口解析失败'));
Sentry.captureMessage('用户主动取消了授权', 'info');

// 用户与标签
Sentry.setUser({ id: 'user_12345', username: 'John Doe' });
Sentry.setTag('page_module', 'checkout');

// 业务面包屑
Sentry.addBreadcrumb({ message: '点击了[确认支付]', category: 'action', level: 'info' });

// 自定义测速
await Sentry.startSpan({ name: 'fetch-user', op: 'http.client' }, async () => { /* ... */ });

// 隐私合规：init({ requireConsent: true }) 后，用户同意隐私协议再补发缓冲
Sentry.setConsent(true);

需要按页面 / 场景精细采样时用 tracesSampler 回调（设置后 tracesSampleRate 被忽略），写法见文档站 · 配置项参考。

国内小程序 / 小游戏合规场景可在初始化时设置 requireConsent: true：同意前 SDK 照常采集但不发网络，事件先入本地缓冲；用户同意后调用 Sentry.setConsent(true) 补发，撤回同意时调用 Sentry.setConsent(false) 重新闸断。

🗺️ Source Map

SDK 默认开启多端堆栈路径归一化（enableSourceMap: true），自动将各平台虚拟路径转为统一 app:/// 前缀，配合 sentry-cli 上传即可解析：

sentry-cli releases files "[email protected]" upload-sourcemaps ./dist \
  --url-prefix "app:///" --ext js --ext map

端到端配置（各构建工具、CI/CD、跨端框架两层 map 串联、验证排查）见 Source Map 完整配置指南。

🎮 小游戏支持

sentry-miniapp 同样适用于微信 / 抖音等小游戏：自动识别环境，异常 / 网络 / 设备监控开箱即用，并额外提供冷启动首帧耗时与帧率 / 卡顿监控。初始化与小程序完全一致，开启 tracesSampleRate 后性能数据会作为独立 transaction 进 Performance 页。

能力矩阵与性能上报细节见文档站 · 支持平台与能力。

📦 主包体积优化

SDK 原始体积约 100KB。很在意主包体积时，可用平台「分包异步化」/「动态加载」把 SDK 移到分包，显著降低主包占用；微信等支持跨分包异步加载的场景有机会做到主包 0KB 占用。

微信分包异步化做法与其他平台 / 框架的核查建议见文档站 · 主包体积优化。

💬 用户反馈

小程序无 DOM，showReportDialog() 已废弃。请自行实现原生表单收集反馈，再调 Sentry.captureFeedback() 提交：

Sentry.captureFeedback({ message: '页面卡住了', name: '张三', email: '[email protected]' });

❓ 常见问题（速览）

• 必须在 onError 里手动上报吗？ 不用，init 会自动挂全局错误监听。
• 网络请求会随错误上报吗？ 会，默认开启，记成 category: xhr 面包屑随错误一起发。
• uni-app（Vue）组件内错误上报率很低？ Vue 吞掉了组件错误，需接 app.config.errorHandler；Taro（React）用错误边界。
• 支持 Session Replay 吗？ 不支持（小程序无 DOM），用面包屑还原现场。
• H5 端怎么办？ 用官方 @sentry/browser，按端条件编译引入。

每条的完整解答见 文档站 · 常见问题。

📖 文档导航

| 文档 | 说明 | |------|------| | 文档站 | 快速接入 / 能力矩阵 / FAQ / Source Map / 示例（推荐，带搜索） | | Taro 接入指南 · uni-app 接入指南 | 跨端框架接入与组件错误处理 | | Source Map 完整配置指南 | 端到端配置、各构建工具、CI/CD、验证排查 | | 多端兼容性报告 | 各小程序平台 API 差异说明 | | 示例项目 | wxapp（原生）/ taro（React）/ uniapp（Vue）三套可运行示例 | | 开发指南 · 贡献指南 | 本地开发、调试与贡献 |

💬 联系与交流

遇到问题？想探讨小程序监控方案？由于微信群二维码有 7 天时效，请添加作者微信（备注 sentry-miniapp），由作者邀请入群：

License

MIT