Skip to content

快速接入 ​

用最小配置把一个测试错误发到 Sentry,确认上报链路打通后,再添加项目需要的监控。

本页面向 2.x,适用于微信、支付宝、字节跳动、钉钉、QQ、百度、快手原生小程序。接入需要 Sentry 官方云服务,或 26.4.2 及以上的自建 Sentry;已有项目升级或后台更旧时,先看版本选择与迁移。

本页是原生小程序的最短接入路径。Taro、uni-app 或小游戏请直接进入 Taro、uni-app或小游戏指南。

1. 安装 ​

在小程序项目的 package.json 所在目录安装;尚无该文件时,先运行 npm init -y:

bash
npm install sentry-miniapp --save
# 或 yarn add sentry-miniapp

原生微信小程序还需要构建 npm:安装或更新 SDK 后,在微信开发者工具中执行「工具 → 构建 npm」,再编译小程序。默认情况下,package.json 须位于 project.config.json 的 miniprogramRoot 目录内;目录分离的项目按微信官方 npm 文档配置手动打包。Taro / uni-app 由框架构建处理依赖,不需要额外执行这个原生步骤。

不使用 npm 时,可从 GitHub Releases 下载对应版本的 sentry-miniapp.umd.js,放入项目的 lib/ 目录,并将下方导入改为 const Sentry = require('./lib/sentry-miniapp.umd.js');。

2. 初始化 ​

在入口顶部、业务模块加载与 App() 调用之前执行 Sentry.init,让监听尽早安装。初始化之前已经发生的异常和请求无法补采。

js
// app.js;放在现有 App() 调用之前
const Sentry = require('sentry-miniapp');

Sentry.init({
  dsn: 'YOUR_DSN', // 替换为 Sentry 项目中的完整 DSN

  // 标识这次发布;按 release 上传 Source Map 时,两边的值须一致
  release: 'my-miniapp@1.0.0',
  environment: 'production',
});

初始化时序

应在 App() 之前初始化。放进 App.onLaunch 时,SDK 无法补回已经发生的启动异常或本次 onLaunch 面包屑,后续异常、网络面包屑和手动上报仍可工作。

晚初始化时,若宿主的原生前台和后台监听均可用,SDK 会继续管理初始化后的 Session;这不包含初始化之前的运行记录。用 Sentry.getDiagnostics() 检查 late_init/lifecycle_unavailable 警告;缺少完整监听时,需要业务显式管理 Session 和前后台边界的 flush()。

默认初始化路径已包含自动异常捕获、Source Map 路径归一化、网络面包屑、Session 与网络状态;通用 Performance/FPS 需显式启用。通常无需手动传 integrations。

如果调用时宿主 API 尚未就绪,Sentry.init() 会返回 undefined。2.3.1 起,宿主可用后,在应用持久入口重新调用即可重试;SDK 不自动轮询或补建实例。仅提前导入模块不会固定失败结果,也无需重载模块。仍应尽量在业务执行及 App() 注册前成功初始化;H5 项目应使用官方浏览器 SDK,详见 初始化失败排查。

先用最小配置跑通事件,再按需要开启性能采样、Logs、隐私同意或其它能力。全部选项见配置项参考。

3. 验证是否打通 ​

主动捕获一个事件,然后到 Sentry「Issues」列表查看:

js
Sentry.captureException(new Error('sentry test'));
// 或 Sentry.captureMessage('sentry test', 'error');

注意

addBreadcrumb(面包屑)不会单独上报——它只在「下一次事件」发生时随事件一起发送。只调用 addBreadcrumb 而不捕获事件,后台会一直没有数据,这不是 SDK 没生效。

4. 常见前置检查 ​

  • 合法域名:在实际运行的 AppID 所对应的小程序后台,把实际上报地址的协议、域名及端口(如有)加入「request 合法域名」。Sentry SaaS 与自托管部署都需要配置;默认取 DSN 的上报地址,配置 tunnel 时取 tunnel 地址。
  • 关闭调试后验收:手机调试模式与开发者工具的「不校验合法域名」会跳过域名校验。验收时关闭这些选项,核对实际请求结果和后台事件;采集提示或 flush 完成不能代替后台接收证据。
  • 真机 vs 开发者工具:微信开发者工具某些环境下的报错不会触发底层 wx.onError,建议在真机预览下测试。
  • uni-app / Taro 框架:组件内的错误可能被框架接住、不冒泡到 wx.onError,需接框架的错误处理。详见 Taro 接入指南、uni-app 接入指南 或 常见问题。

例如,DSN 为 https://publickey@o123.ingest.us.sentry.io/456 时,填写 https://o123.ingest.us.sentry.io,保留 .us 等实际域名部分。Sentry 控制台的网址、DSN 中的 key 和项目路径都不填入域名配置。

仍然没有数据时,按 FAQ · 初始化后没有数据 的完整清单逐项排查。

下一步 ​

基于 @sentry/core 的跨端小程序与小游戏 SDK · MIT Licensed