Sentry Miniapp

Sentry Miniapp#

资源概述#

Sentry Miniapp 是一个基于 Sentry JavaScript V10 SDK 核心构建的小程序监控 SDK。它将 Sentry 的异常追踪和性能监控能力引入小程序生态，为开发者提供生产环境下的错误收集、性能分析、用户行为追踪等完整可观测性方案。

核心数据：

GitHub：lizhiyao/sentry-miniapp
Stars：647 / Forks：142 / License：MIT
npm 包：sentry-miniapp v1.13.2
最近更新：2026-04-13
主语言：TypeScript（89.6%）
测试覆盖率：100%

支持平台：微信、支付宝、字节跳动、百度、QQ、钉钉、快手 支持框架：原生小程序、Taro、uni-app

典型场景：

生产环境 JS 异常自动捕获与上报
小程序性能瓶颈分析（FCP / LCP / 资源加载）
跨端小程序统一监控方案
弱网环境下的可靠错误上报（离线缓存 + 重试）

设计规范#

架构设计#

SDK 基于 @sentry/core V10 核心模块构建，内置 API 抹平引擎，将不同小程序平台的差异化 API 统一为 Sentry 标准接口：

生命周期异常捕获：自动监听 onError、onUnhandledRejection、onPageNotFound、onMemoryWarning
行为面包屑：自动记录设备信息、用户点击/触摸、网络请求（XHR/Fetch）、路由跳转
性能采集：集成小程序 Performance API，采集导航性能、渲染性能、资源加载耗时
堆栈解析：内置多平台堆栈解析器，支持 V8/Safari/JavaScriptCore 格式

离线缓存机制#

专为小程序网络环境设计的可靠上报方案：

发送失败时自动缓存 Event 到本地 Storage
监听网络状态恢复事件
网络恢复后静默重试上报
确保数据不丢失

审核规范#

合法域名配置#

使用前必须在小程序管理后台将 Sentry 上报接口域名添加到 request 合法域名列表：

Sentry SaaS：sentry.io 相关域名
私有部署：自建 Sentry 服务器域名

隐私合规#

SDK 会采集设备信息（系统、网络、场景），需在用户隐私保护指引中声明：

收集设备信息（wx.getSystemInfoSync）
收集网络状态信息（wx.getNetworkType）

开发指南#

快速上手#

code

// app.js — 在最顶部初始化（App() 之前）
import * as Sentry from 'sentry-miniapp';

Sentry.init({
  dsn: 'https://<key>@sentry.io/<project>',
  environment: 'production',
  release: 'my-app@1.0.0',
  
  // 小程序特性配置
  platform: 'wechat',           // 当前平台
  enableSystemInfo: true,        // 自动采集系统信息
  enableUserInteractionBreadcrumbs: true,  // 记录用户点击
  enableNavigationBreadcrumbs: true,       // 记录路由跳转
  enableOfflineCache: true,      // 离线缓存
  
  // 性能监控
  tracesSampleRate: 1.0,         // 性能采样率
});

App({ /* ... */ });

SourceMap 上传#

code

# 使用 sentry-cli 上传 SourceMap
sentry-cli sourcemaps upload --release my-app@1.0.0 \
  --ext .js --ext .map ./dist

AI 辅助接入#

code

# Claude Code / Cursor 自动引导接入
npx skills add https://github.com/lizhiyao/sentry-miniapp --skill sentry-miniapp-sdk

常见陷阱#

合法域名未配置：忘记在小程序后台添加 Sentry 域名到 request 白名单 → 上报全部失败
SourceMap 不匹配：release 版本号与上传 SourceMap 时的版本号不一致 → 堆栈无法还原
采样率过高：生产环境 tracesSampleRate: 1.0 会采集全部性能数据，可能超出 Sentry 配额
Storage 容量：离线缓存大量异常到 Storage 可能影响小程序正常运行，建议设置 maxCacheItems

从 Web Sentry 迁移#

Web SDK	Miniapp SDK	说明
`Sentry.init()`	`Sentry.init({ platform })`	需指定 platform 参数
`window.onerror`	`onError` 生命周期	自动拦截小程序生命周期
`fetch` / `XHR`	`wx.request`	自动包装小程序网络 API
`localStorage`	`wx.setStorageSync`	离线缓存使用小程序 Storage

生态资源#

支持的小程序平台#

平台	platform 参数	状态
微信	`wechat`	✅ 完整支持
支付宝	`alipay`	✅ 完整支持
字节跳动	`bytedance`	✅ 完整支持
百度	`baidu`	✅ 完整支持
QQ	`qq`	✅ 完整支持
钉钉	`dd`	✅ 完整支持
快手	`kuaishou`	✅ 完整支持

跨端框架#

框架	支持	说明
Taro	✅	直接安装使用，无需额外配置
uni-app	✅	直接安装使用，无需额外配置

版本更新#

当前版本：v1.13.2（npm）#

版本演进#

v1.x（2026）：全新架构，基于 Sentry V10 核心，全面支持多端小程序 + 跨端框架
- v1.13.2：最新稳定版（2026-04）
- 100% 测试覆盖率
- 内联依赖，无需额外安装 @sentry/core
- 支持分布式追踪（sentry-trace / baggage 头注入）
- Session 健康监控
- AI 辅助接入（Claude Code / Cursor）
v0.x（已停更）：旧版本，基于早期 Sentry 核心

数据来源#

GitHub API（stars / forks / license / lastPush）
npm registry（版本号 / 依赖信息）
官方 README 完整原文

特性

详细文档

Sentry Miniapp#

资源概述#

设计规范#

架构设计#

离线缓存机制#

审核规范#

合法域名配置#

隐私合规#

开发指南#

快速上手#

SourceMap 上传#

AI 辅助接入#

常见陷阱#

从 Web Sentry 迁移#

生态资源#

支持的小程序平台#

跨端框架#

相关项目#

版本更新#

当前版本：v1.13.2（npm）#

版本演进#

数据来源#