sentry-react-native-setup

Sentry React Native 设置

使用官方向导 CLI 在 React Native 项目中安装并配置 Sentry。

何时调用此技能

• 用户要求在 React Native 应用中“添加 Sentry”或“安装 Sentry”
• 用户希望在 React Native 或 Expo 中进行错误监控、日志记录或追踪
• 用户提到“@sentry/react-native”或移动端错误追踪

重要： 下面的配置选项和代码示例仅供参考。实现前请务必对照 docs.sentry.io 核实，因为 API 和默认值可能已发生变化。

向导设置（推荐）

npx @sentry/wizard@latest -i reactNative

向导会做什么

任务	描述
安装 SDK	添加 @sentry/react-native 包
Metro 配置	将 @sentry/react-native/metro 添加到 metro.config.js
Expo 配置	将 @sentry/react-native/expo 添加到 app.json
Android 设置	启用 Gradle 构建步骤以生成 source maps
iOS 设置	包装 Xcode 构建阶段，添加调试符号上传
Pod 安装	为 iOS 运行 pod install
凭据	存储在 ios/sentry.properties、android/sentry.properties、env.local
初始化代码	在 App.tsx 或 _layout.tsx 中配置 Sentry

手动配置

如果不使用向导，请添加到应用入口点：

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  sendDefaultPii: true,
  
  // Tracing
  tracesSampleRate: 1.0,
  
  // Logs
  enableLogs: true,
  
  // Profiling
  profilesSampleRate: 1.0,
  
  // Session Replay
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  integrations: [Sentry.mobileReplayIntegration()],
});

包装你的应用

export default Sentry.wrap(App);

Expo 项目

对于 Expo，请遵循 Expo 专属设置：

npx @sentry/wizard@latest -i reactNative

适用于 managed 和 bare Expo 项目。

配置选项

选项	描述	默认值
dsn	Sentry DSN	必填
sendDefaultPii	包含用户数据	false
tracesSampleRate	被追踪的事务百分比	0
profilesSampleRate	被性能分析的追踪百分比	0
enableLogs	将日志发送到 Sentry	false
replaysOnErrorSampleRate	被回放的错误会话百分比	0
replaysSessionSampleRate	被回放的全部会话百分比	0

创建/修改的文件

文件	用途
App.js / _layout.tsx	Sentry 初始化
metro.config.js	Metro 打包器配置
app.json	Expo 配置（如果是 Expo）
ios/sentry.properties	iOS 构建凭据
android/sentry.properties	Android 构建凭据
env.local	环境变量

环境变量

SENTRY_DSN=https://[email protected]/456
SENTRY_AUTH_TOKEN=sntrys_xxx
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project

验证

添加测试错误：

throw new Error("My first Sentry error!");

或使用测试按钮：

<Button title="Test Sentry" onPress={() => { throw new Error("Test"); }} />

Source Maps

当向导配置以下内容时，source maps 会在构建期间自动上传：

• Android：Gradle 插件
• iOS：Xcode 构建阶段

故障排除

问题	解决方案
向导失败	尝试手动设置，检查 Node 版本
iOS 构建失败	运行 cd ios && pod install
Source maps 未上传	验证 sentry.properties 文件包含 auth token
Expo 错误	确保使用兼容的 Expo SDK 版本
应用未包装	添加 export default Sentry.wrap(App)