Taro 小程序接入 Sentry:React 错误上报
Taro 小程序端使用 sentry-miniapp 接入 Sentry。 在业务模块加载前初始化,再将 React 组件错误交给错误边界上报;同时构建 H5 时,按端选择 SDK。
本页以 Taro 4 + React + TypeScript 编译到微信小程序为例。Taro 也支持 Vue,Vue 项目的组件错误需接入 errorHandler,见 Vue 错误处理。可运行示例见 examples/taro。
接入前确认
- 已创建 Sentry 项目并复制完整 DSN;2.x 需要 Sentry 官方云服务,或 26.4.2 及以上的自建 Sentry。已有项目升级或后台更旧时,先看版本选择与迁移。
- 微信小程序后台已配置实际上报地址的
request合法域名,见域名检查。 - 需要定位到
.tsx源码时,准备上传同一构建的 JS 与 Source Map,见上线指南。
为什么不能直接用 @sentry/browser
Taro 小程序产物运行在宿主逻辑层,不能直接沿用浏览器 SDK 的默认采集与发送方式:
- 小程序可能提供
window别名,但通常缺少 DOM、浏览器fetch和XMLHttpRequest;仅有别名不能满足官方 Web SDK 的运行条件; - 逻辑层无法直接访问渲染层的 DOM;请求须使用平台 API(如微信
wx.request、支付宝my.httpRequest),需要 transport 与宿主适配。
sentry-miniapp 复用 Sentry Core,并适配这些宿主入口。小程序端用本 SDK,H5 端选择官方 Web SDK;分端配置见下文。
1. 安装
npm install sentry-miniapp --save2. 初始化封装
新建 src/utils/sentry.ts,集中放初始化(DSN、采样、标签):
import * as Sentry from 'sentry-miniapp';
Sentry.init({
dsn: 'YOUR_DSN', // 替换为 Sentry 项目中的完整 DSN
release: 'my-taro-app@1.0.0', // 与上传 Source Map 时的 release 完全一致
environment: 'production',
});
Sentry.setTag('app.framework', 'taro-react');
export default Sentry;平台会自动识别。默认初始化路径已含自动异常捕获、Source Map 路径归一化、网络面包屑、Session 与网络状态监控,通常无需手动传 integrations。
3. 尽早初始化
在 src/app.tsx 顶部引入封装(引入即执行 init),确保先于业务请求、能捕获启动阶段异常:
import './utils/sentry'; // 保留初始化副作用,放在业务模块之前
import type { PropsWithChildren } from 'react';
import SentryBoundary from './components/SentryBoundary';
function App({ children }: PropsWithChildren) {
return <SentryBoundary>{children}</SentryBoundary>;
}
export default App;4. 组件错误:用 React 错误边界
React 错误边界可以捕获子树渲染、构造和生命周期中的错误,附加 componentStack 并展示备用界面。它不能覆盖事件处理器与任意异步任务;详见 React 错误边界说明。新建 src/components/SentryBoundary.tsx:
import { Component, type ErrorInfo, type ReactNode } from 'react';
import { View, Text } from '@tarojs/components';
import Sentry from '../utils/sentry';
export default class SentryBoundary extends Component<{ children: ReactNode }, { hasError: boolean }> {
state = { hasError: false };
static getDerivedStateFromError() {
return { hasError: true };
}
componentDidCatch(error: Error, info: ErrorInfo) {
Sentry.captureException(error, { extra: { componentStack: info.componentStack } });
console.error(error);
}
render() {
if (this.state.hasError) {
return (
<View style={{ padding: '40rpx', color: '#c0392b' }}>
<Text>页面暂时无法显示,请重新进入。</Text>
</View>
);
}
return this.props.children;
}
}错误边界的范围
事件处理器、定时器和一般异步任务不在错误边界范围内。业务已捕获的异常可主动调用 captureException();未处理异常由宿主全局监听或 TryCatch 集成按能力捕获。
这是 Taro(React) 对应 uni-app(Vue)
errorHandler的做法。对比见 常见问题 · 组件内错误。
5. 分端接入(同时要 H5)
若 Taro 工程还编译 H5,用 process.env.TARO_ENV 分端引入——小程序用 sentry-miniapp,H5 用功能完整、官方维护的 @sentry/browser:
用下方片段替换初始化封装中的 SDK 导入,再对选出的 SDK 调用 init()。DSN、release 和 environment 可共用;平台专属选项放在对应分支。
npm install sentry-miniapp @sentry/browser --savelet Sentry;
if (process.env.TARO_ENV === 'h5') {
Sentry = require('@sentry/browser'); // H5 端
} else {
Sentry = require('sentry-miniapp'); // 小程序端
}6. 其它
- 网络:
Taro.request最终走对应小程序端被包裹的全局请求 API,请求会自动记成xhr面包屑、随错误事件上报,无需额外配置。 - 性能与追踪:需要独立性能数据时再设置采样率,见性能与链路追踪。
- Source Map:Taro 经过编译,错误栈是编译后代码,需上传 Source Map 才能还原。配置见 Source Map 上线指南;真机堆栈出现
appservice.app.js时,继续看微信两层映射。
验证接入是否完成
分别验证上报链路和组件错误捕获:
- 在测试页面的按钮回调中调用
Sentry.captureException(new Error('taro delivery test')),到正确的 Sentry 项目和环境中找到该事件。这一步确认手动上报链路。 - 在错误边界包裹的子组件中,临时让渲染函数抛出一个带独特消息的
Error,不要手动调用captureException。确认备用界面出现,并在 Sentry 找到该组件错误及componentStack。可参考示例测试页的「触发组件渲染错误」按钮。 - 第二步成功后移除测试代码。只完成第一步,不能证明错误边界覆盖了你的实际页面;普通按钮回调抛错也不能用于验证 React 渲染错误捕获。
没有事件时,先看上报链路排查;只有组件错误缺失时,检查该组件是否处于实际生效的错误边界内。
下一步
页面回放
需要定位出错前的界面变化时,Taro 4 + webpack5 微信 WebView 项目使用 sentry-miniapp 2.2.0 或更新版本,按页面回放指南配置录制器和自动构建插件。配置一次后继续使用原来的构建/watch 命令,无需逐页修改模板。文字默认遮蔽,输入、媒体和原生绘制保留占位;源码示例还提供不消耗 Sentry 配额的本地录制模式。
