英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

Sentry Miniapp SDK — 小程序监控 SDK

简体中文 | English

为小程序与小游戏接入 Sentry，结合设备、操作和请求记录排查线上异常；按需开启性能采样，分析请求与业务操作的耗时。

支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手小程序，以及微信和抖音小游戏，适用于原生、Taro 和 uni-app 项目。

快速开始 · 完整文档 · 示例工程

✨ 核心能力与适用场景

自动采集范围取决于平台能力；React / Vue 组件错误需要接入框架错误处理，小游戏帧率监控需要主动开启。按项目类型查看 Taro、uni-app、小游戏指南或平台支持范围。

接入要求

本文与当前官网面向 2.x 正式版。已有 1.x 项目升级，或自建后台暂时无法升级时，先看版本选择与迁移说明。

使用 Sentry 官方云服务，或 26.4.2 及以上的自建 Sentry。更旧的自建后台不在 2.x 支持范围内；只收到错误事件不能证明其它监控能力兼容。

🚀 5 分钟跑通

接入前确认：

• 已确认 Sentry 后台满足接入要求，创建好项目并复制该项目的 DSN。
• 小程序后台已把 Sentry 上报域名加入 request 合法域名。
• 宿主具备基础 JavaScript 能力；标准方法补齐和可选观测的降级边界见运行时兼容说明。

安装：

npm install sentry-miniapp

原生微信项目还需在开发者工具中执行「工具 → 构建 npm」；目录要求见快速接入。Taro / uni-app 由框架构建处理依赖。

不使用 npm 时，可从 GitHub Releases 下载对应版本的 sentry-miniapp.umd.js，放入项目的 lib/ 目录，将下方导入改为 const Sentry = require('./lib/sentry-miniapp.umd.js');。调试源码仓库中的微信示例时，运行 yarn build:miniapp 生成示例依赖。

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

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

Sentry.init({
  dsn: 'YOUR_DSN', // 复制 Sentry 项目中的完整 DSN
  release: 'my-project@1.0.0', // 与上传 Source Map 时的 release 一致
  environment: 'production',
});

App({ onLaunch() {} });

验证是否打通：

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

然后到 Sentry 的 Issues 列表查看事件。

确认错误上报后，再按项目流量配置 tracesSampleRate 开启性能监控，见性能与链路追踪。最小接入配置不启动性能采样。

没看到事件时，优先确认 DSN、合法域名、初始化位置和采样配置；完整排查清单见 文档站 · 快速接入 与 FAQ。

🤖 AI Coding Agent 辅助接入

在自己的小程序 / 小游戏项目中安装接入 skill：

npx --yes degit lizhiyao/sentry-miniapp/.agents/skills/sentry-miniapp-sdk .agents/skills/sentry-miniapp-sdk

然后让 Agent「使用 sentry-miniapp-sdk skill，识别平台和框架，完成初始化并给出验证步骤」。未自动发现时，让它读取 .agents/skills/sentry-miniapp-sdk/SKILL.md；使用方法见 skill 指南。

🧭 下一步看哪里

已经跑通基础上报后，按你下一步要做的事进入对应文档：

实验性微信页面回放

想查看出错前的界面变化，可按需启用微信页面回放。它录制选定页面的采样布局、文字变化与点击；构建工具为支持的节点和静态组件生成标记。需要 sentry-miniapp 2.1.0 或更新版本，并按指南安装回放集成、生成页面标记；目前仅适用于微信普通 WebView 小程序。

Taro 4／webpack5 和 uni-app Vue 3／Vite 项目使用 2.2.0 或更新版本，配置一次构建插件后，正常构建和开发时会自动生成标记，无需逐页修改模板。

源码示例也提供本地录制与播放：导出录制后在 PC 浏览器查看，不使用 Sentry 云服务额度。

💬 联系与交流

如果是接入问题或线上排查，建议优先在 GitHub 提出来，方便把排查结论沉淀为可搜索的答案：

• Bug / 没有数据 / Source Map 不还原：提交 Issue，请附 SDK 版本、目标平台、复现步骤、关键配置和 Sentry.getDiagnostics() 输出。
• 功能建议 / 监控方案讨论：发起 Discussion，说明业务场景、目标平台和期望行为。

分享配置和日志前，请移除 Auth Token、AppSecret 和用户隐私数据。

想实时交流小程序 / 小游戏监控方案，可以加入微信群。由于微信群二维码有 7 天时效，请添加作者微信（备注 sentry-miniapp），由作者邀请入群：