sentry-react-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry React Setup

Sentry React 配置

Install and configure Sentry in React projects.

在React项目中安装并配置Sentry。

Invoke This Skill When

何时调用此技能

User asks to "add Sentry to React" or "install Sentry" in a React app
User wants error monitoring, logging, or tracing in React
User mentions "@sentry/react" or React error boundaries

用户要求“在React中添加Sentry”或在React应用中“安装Sentry”
用户需要在React中实现错误监控、日志记录或追踪功能
用户提到“@sentry/react”或React错误边界

Install

安装

bash

npm install @sentry/react --save

bash

npm install @sentry/react --save

Configure

配置

Create

src/instrument.js

(must be imported first in your app):

javascript

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

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  sendDefaultPii: true,
  
  // Tracing
  integrations: [Sentry.browserTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/],
  
  // Session Replay
  integrations: [Sentry.replayIntegration()],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  
  // Logs
  enableLogs: true,
});

创建

src/instrument.js

文件（必须在应用中最先导入）：

javascript

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

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  sendDefaultPii: true,
  
  // 追踪
  integrations: [Sentry.browserTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/],
  
  // 会话重放
  integrations: [Sentry.replayIntegration()],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  
  // 日志
  enableLogs: true,
});

Import First in Entry Point

在入口文件中最先导入

javascript

// src/index.js or src/main.jsx
import "./instrument";  // Must be first!
import App from "./App";
import { createRoot } from "react-dom/client";

const root = createRoot(document.getElementById("app"));
root.render(<App />);

javascript

// src/index.js 或 src/main.jsx
import "./instrument";  // 必须最先导入！
import App from "./App";
import { createRoot } from "react-dom/client";

const root = createRoot(document.getElementById("app"));
root.render(<App />);

Error Handling

错误处理

React 19+

React 19及以上版本

Use error hooks with

createRoot

javascript

import { createRoot } from "react-dom/client";
import * as Sentry from "@sentry/react";

const root = createRoot(document.getElementById("app"), {
  onUncaughtError: Sentry.reactErrorHandler(),
  onCaughtError: Sentry.reactErrorHandler(),
  onRecoverableError: Sentry.reactErrorHandler(),
});

结合

createRoot

使用错误钩子：

javascript

import { createRoot } from "react-dom/client";
import * as Sentry from "@sentry/react";

const root = createRoot(document.getElementById("app"), {
  onUncaughtError: Sentry.reactErrorHandler(),
  onCaughtError: Sentry.reactErrorHandler(),
  onRecoverableError: Sentry.reactErrorHandler(),
});

React <19

React 19以下版本

Use ErrorBoundary component:

javascript

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

<Sentry.ErrorBoundary fallback={<p>An error occurred</p>}>
  <MyComponent />
</Sentry.ErrorBoundary>

使用ErrorBoundary组件：

javascript

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

<Sentry.ErrorBoundary fallback={<p>发生错误</p>}>
  <MyComponent />
</Sentry.ErrorBoundary>

React Router Integration

React Router集成

Router Version	Integration
v7 (non-framework)	`Sentry.reactRouterV7BrowserTracingIntegration`
v6	`Sentry.reactRouterV6BrowserTracingIntegration`
v4/v5	`Sentry.reactRouterV5BrowserTracingIntegration`

路由版本	集成方式
v7（非框架版）	`Sentry.reactRouterV7BrowserTracingIntegration`
v6	`Sentry.reactRouterV6BrowserTracingIntegration`
v4/v5	`Sentry.reactRouterV5BrowserTracingIntegration`

Redux Integration (Optional)

Redux集成（可选）

javascript

import * as Sentry from "@sentry/react";
import { configureStore } from "@reduxjs/toolkit";

const store = configureStore({
  reducer,
  enhancers: (getDefaultEnhancers) =>
    getDefaultEnhancers().concat(Sentry.createReduxEnhancer()),
});

javascript

import * as Sentry from "@sentry/react";
import { configureStore } from "@reduxjs/toolkit";

const store = configureStore({
  reducer,
  enhancers: (getDefaultEnhancers) =>
    getDefaultEnhancers().concat(Sentry.createReduxEnhancer()),
});

Source Maps

源映射

Upload source maps for readable stack traces:

bash

npx @sentry/wizard@latest -i sourcemaps

上传源映射以获得可读的堆栈追踪：

bash

npx @sentry/wizard@latest -i sourcemaps

Environment Variables

环境变量

bash

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

bash

REACT_APP_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 button to trigger error:

javascript

<button onClick={() => { throw new Error("Sentry Test Error"); }}>
  Test Sentry
</button>

添加测试按钮触发错误：

javascript

<button onClick={() => { throw new Error("Sentry Test Error"); }}>
  测试Sentry
</button>

Troubleshooting

故障排查

Issue	Solution
Errors not captured	Ensure `instrument.js` is imported first
Source maps not working	Run sourcemaps wizard, verify auth token
React Router spans missing	Add correct router integration for your version

问题	解决方案
错误未被捕获	确保 `instrument.js` 是最先导入的文件
源映射不生效	运行源映射向导，验证认证令牌
React Router追踪数据缺失	添加对应版本的路由集成