sentry-react-native-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry React Native Setup

Sentry React Native 配置指南

Install and configure Sentry in React Native projects using the official wizard CLI.

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

Invoke This Skill When

何时调用此技能

User asks to "add Sentry to React Native" or "install Sentry" in a React Native app
User wants error monitoring, logging, or tracing in React Native or Expo
User mentions "@sentry/react-native" or mobile error tracking

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

Wizard Setup (Recommended)

向导配置（推荐）

bash

npx @sentry/wizard@latest -i reactNative

bash

npx @sentry/wizard@latest -i reactNative

What the Wizard Does

向导功能说明

Task	Description
Install SDK	Adds `@sentry/react-native` package
Metro config	Adds `@sentry/react-native/metro` to `metro.config.js`
Expo config	Adds `@sentry/react-native/expo` to `app.json`
Android setup	Enables Gradle build step for source maps
iOS setup	Wraps Xcode build phase, adds debug symbol upload
Pod install	Runs `pod install` for iOS
Credentials	Stores in `ios/sentry.properties` , `android/sentry.properties` , `.env.local`
Init code	Configures Sentry in `App.tsx` or `_layout.tsx`

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

Manual Configuration

手动配置

If not using wizard, add to your app entry point:

javascript

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()],
});

如果不使用向导，可在应用入口文件中添加以下代码：

javascript

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

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  sendDefaultPii: true,
  
  // 追踪配置
  tracesSampleRate: 1.0,
  
  // 日志配置
  enableLogs: true,
  
  // 性能分析配置
  profilesSampleRate: 1.0,
  
  // 会话重放配置
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  integrations: [Sentry.mobileReplayIntegration()],
});

Wrap Your App

包装应用组件

javascript

export default Sentry.wrap(App);

javascript

export default Sentry.wrap(App);

Expo Projects

Expo项目配置

For Expo, follow the Expo-specific setup:

bash

npx @sentry/wizard@latest -i reactNative

Works for both managed and bare Expo projects.

针对Expo项目，请遵循Expo专属配置指南:

bash

npx @sentry/wizard@latest -i reactNative

该方法适用于托管式和裸架构Expo项目。

Configuration Options

配置选项

Option	Description	Default
`dsn`	Sentry DSN	Required
`sendDefaultPii`	Include user data	`false`
`tracesSampleRate`	% of transactions traced	`0`
`profilesSampleRate`	% of traces profiled	`0`
`enableLogs`	Send logs to Sentry	`false`
`replaysOnErrorSampleRate`	% of error sessions replayed	`0`
`replaysSessionSampleRate`	% of all sessions replayed	`0`

选项	描述	默认值
`dsn`	Sentry DSN地址	必填
`sendDefaultPii`	是否包含用户数据	`false`
`tracesSampleRate`	被追踪的事务占比	`0`
`profilesSampleRate`	被分析的追踪占比	`0`
`enableLogs`	是否将日志发送至Sentry	`false`
`replaysOnErrorSampleRate`	发生错误的会话中被重放的占比	`0`
`replaysSessionSampleRate`	所有会话中被重放的占比	`0`

Files Created/Modified

被创建/修改的文件

File	Purpose
`App.js` / `_layout.tsx`	Sentry initialization
`metro.config.js`	Metro bundler config
`app.json`	Expo config (if Expo)
`ios/sentry.properties`	iOS build credentials
`android/sentry.properties`	Android build credentials
`.env.local`	Environment variables

文件	用途
`App.js` / `_layout.tsx`	Sentry初始化代码
`metro.config.js`	Metro打包器配置
`app.json`	Expo配置（若为Expo项目）
`ios/sentry.properties`	iOS构建凭证
`android/sentry.properties`	Android构建凭证
`.env.local`	环境变量

Environment Variables

环境变量

bash

SENTRY_DSN=https://xxx@o123.ingest.sentry.io/456
SENTRY_AUTH_TOKEN=sntrys_xxx
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project

bash

SENTRY_DSN=https://xxx@o123.ingest.sentry.io/456
SENTRY_AUTH_TOKEN=sntrys_xxx
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project

Verification

验证配置

Add test error:

javascript

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

Or use a test button:

javascript

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

添加测试错误：

javascript

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

或添加测试按钮：

javascript

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

Source Maps

源码映射

Source maps are automatically uploaded during build when wizard configures:

Android: Gradle plugin
iOS: Xcode build phase

当向导完成配置后，源码映射会在构建过程中自动上传：

Android：通过Gradle插件
iOS：通过Xcode构建阶段

Troubleshooting

故障排除

Issue	Solution
Wizard fails	Try manual setup, check Node version
iOS build fails	Run `cd ios && pod install`
Source maps not uploading	Verify `sentry.properties` files have auth token
Expo errors	Ensure using compatible Expo SDK version
App not wrapped	Add `export default Sentry.wrap(App)`

问题	解决方案
向导运行失败	尝试手动配置，检查Node版本
iOS构建失败	运行 `cd ios && pod install`
源码映射未上传	验证 `sentry.properties` 文件中是否包含正确的认证令牌
Expo项目报错	确保使用兼容的Expo SDK版本
应用未被包装	添加 `export default Sentry.wrap(App)` 代码