sentry-react-setup

Sentry React 设置

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

何时调用本技能

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

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

安装

npm install @sentry/react --save

配置

在项目根目录创建 instrument.js（必须在应用中最先导入）：

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

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

在入口点最先导入

// 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 />);

错误处理

React 19+

将错误钩子与 createRoot 结合使用：

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

使用 ErrorBoundary 组件：

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

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

路由集成

路由	集成
React Router v7	Sentry.reactRouterV7BrowserTracingIntegration
React Router v6	Sentry.reactRouterV6BrowserTracingIntegration
React Router v4/v5	Sentry.reactRouterV5BrowserTracingIntegration（两者共用）
TanStack Router	参见 TanStack Router 文档

Redux 集成（可选）

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

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

Source Maps

上传 source maps 以获得可读的堆栈跟踪：

npx @sentry/wizard@latest -i sourcemaps

环境变量

SENTRY_DSN=https://[email protected]/456
SENTRY_AUTH_TOKEN=sntrys_xxx  # Used by sentry-cli / source maps, not the SDK
SENTRY_ORG=my-org              # Used by sentry-cli, not the SDK
SENTRY_PROJECT=my-project      # Used by sentry-cli, not the SDK

注意： SDK 会自动读取 SENTRY_DSN。如果使用 Create React App，请加上 REACT_APP_ 前缀；对于 Vite，请使用 VITE_。SENTRY_AUTH_TOKEN/ORG/PROJECT 由 sentry-cli 用于 source map 上传，而不是由浏览器 SDK 使用。

验证

添加测试按钮以触发错误：

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

故障排除

问题	解决方案
错误未被捕获	确保 instrument.js 最先被导入
Source maps 未生效	运行 sourcemaps 向导，验证 auth token
React Router spans 缺失	为你的版本添加正确的路由集成