sentry-react-sdk

所有技能 > SDK 设置 > React SDK

Sentry React SDK

一款提供明确建议的向导，可扫描你的 React 项目并引导你完成 Sentry 的完整设置。

在以下情况下调用此技能

• 用户要求“将 Sentry 添加到 React”或在 React 应用中“设置 Sentry”
• 用户希望在 React 中进行错误监控、跟踪、会话回放、性能分析或日志记录
• 用户提到 @sentry/react、React Sentry SDK 或 Sentry 错误边界
• 用户希望监控 React Router v5/v6/v7 非框架模式下的导航、Redux 状态或组件性能

如果项目使用 @sentry/react-router 的 React Router 框架模式，请改用 sentry-react-router-framework-sdk，而不是此技能。

注意： 以下 SDK 版本和 API 反映的是撰写本文时 Sentry 文档的当前内容（@sentry/react ≥8.0.0）。 实施前，请务必根据 docs.sentry.io/platforms/javascript/guides/react/ 进行确认。

---

阶段 1：检测

在提出任何建议之前，运行以下命令以了解项目：

# Detect React version
cat package.json | grep -E '"react"|"react-dom"'

# Check for existing Sentry
cat package.json | grep '"@sentry/'

# Detect router and framework mode hints
cat package.json | grep -E '"react-router-dom"|"react-router"|"@react-router/"|"@tanstack/react-router"|"@sentry/react-router"'

# Detect state management
cat package.json | grep -E '"redux"|"@reduxjs/toolkit"'

# Detect build tool
ls vite.config.ts vite.config.js webpack.config.js craco.config.js 2>/dev/null
cat package.json | grep -E '"vite"|"react-scripts"|"webpack"'

# Detect logging libraries
cat package.json | grep -E '"pino"|"winston"|"loglevel"'

# Check for companion backend in adjacent directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile ../pom.xml 2>/dev/null | head -3

需要确定的内容：

问题	影响
React 19+？	使用 reactErrorHandler() hook 模式
React <19？	使用 Sentry.ErrorBoundary
项目中已有 @sentry/react？	跳过安装，直接配置功能
是否存在 React Router 框架模式标志（@sentry/react-router、@react-router/*）？	使用 sentry-react-router-framework-sdk
react-router-dom v5 / v6 / v7？	决定使用哪种路由器集成
是否使用 @tanstack/react-router？	使用 tanstackRouterBrowserTracingIntegration()
是否使用 Redux？	建议使用 createReduxEnhancer()
是否检测到 Vite？	通过 sentryVitePlugin 上传源映射
是否使用 CRA（react-scripts）？	通过 CRACO 中的 @sentry/webpack-plugin 上传源映射
是否找到后端目录？	触发阶段 4 的交叉链接建议

---

阶段 2：推荐

根据发现的情况给出具体建议。不要提出开放式问题，而要先给出方案：

推荐（核心覆盖）：

• ✅ 错误监控 — 始终启用；捕获未处理的错误、React 错误边界以及 React 19 hooks
• ✅ 跟踪 — React SPA 可从页面加载、导航和 API 调用跟踪中受益
• ✅ 会话回放 — 推荐用于面向用户的应用；记录错误发生前后的会话

可选（增强可观测性）：

• ⚡ 日志记录 — 通过 Sentry.logger.* 记录结构化日志；需要搜索结构化日志时建议启用
• ⚡ 性能分析 — JS Self-Profiling API（⚠️ 实验性功能；需要跨源隔离响应头）

推荐逻辑：

功能	推荐条件
错误监控	始终 — 不可或缺的基础功能
跟踪	React SPA 始终启用 — 页面加载和导航 span 价值很高
会话回放	面向用户的应用、登录流程或结账页面
日志记录	应用需要搜索结构化日志，或关联日志与跟踪
性能分析	对性能要求较高的应用；服务器发送 Document-Policy: js-profiling 响应头

React 专属扩展：

• 检测到 React 19 → 在 createRoot 上设置 reactErrorHandler()
• 检测到 React Router v5/v6/v7 非框架模式 → 配置匹配的路由器集成（参见阶段 3）
• 检测到 React Router 框架模式 → 切换到 sentry-react-router-framework-sdk
• 检测到 Redux → 将 createReduxEnhancer() 添加到 Redux store
• 检测到 Vite → 配置 sentryVitePlugin 上传源映射（这对获得可读的堆栈跟踪至关重要）

建议：“我推荐设置错误监控 + 跟踪 + 会话回放。要我也添加日志记录或性能分析吗？”

---

阶段 3：引导

安装

npm install @sentry/react --save

创建 src/instrument.ts

Sentry 必须在任何其他代码运行之前初始化。将 Sentry.init() 放在专用的旁置文件中：

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

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN, // Adjust per build tool (see table below)
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION, // inject at build time

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/react/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  // Tracing
  tracesSampleRate: 1.0, // lower to 0.1–0.2 in production
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],

  // Session Replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,
});

不同构建工具对应的 DSN 环境变量：

构建工具	变量名	在代码中的访问方式
Vite	VITE_SENTRY_DSN	import.meta.env.VITE_SENTRY_DSN
Create React App	REACT_APP_SENTRY_DSN	process.env.REACT_APP_SENTRY_DSN
自定义 webpack	SENTRY_DSN	process.env.SENTRY_DSN

入口文件设置

在入口文件中，将 instrument.ts 作为第一个导入项：

// src/main.tsx (Vite) or src/index.tsx (CRA/webpack)
import "./instrument";              // ← MUST be first

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

针对不同 React 版本的错误处理

React 19+ —— 在 createRoot 上使用 reactErrorHandler()：

import { reactErrorHandler } from "@sentry/react";

createRoot(document.getElementById("root")!, {
  onUncaughtError: reactErrorHandler(),
  onCaughtError: reactErrorHandler(),
  onRecoverableError: reactErrorHandler(),
}).render(<App />);

React <19 —— 使用 Sentry.ErrorBoundary 包装应用：

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

createRoot(document.getElementById("root")!).render(
  <Sentry.ErrorBoundary fallback={<p>Something went wrong</p>} showDialog>
    <App />
  </Sentry.ErrorBoundary>
);

对于任何需要独立捕获错误的子树（路由部分、小组件等），请使用 <Sentry.ErrorBoundary>。

路由集成

为你的路由器配置匹配的集成（非框架模式）：

路由器	集成	说明
React Router v7	reactRouterV7BrowserTracingIntegration	从 react-router 导入 useEffect、useLocation、useNavigationType、createRoutesFromChildren、matchRoutes
React Router v6	reactRouterV6BrowserTracingIntegration	从 react-router-dom 导入 useEffect、useLocation、useNavigationType、createRoutesFromChildren、matchRoutes
React Router v5	reactRouterV5BrowserTracingIntegration	使用 withSentryRouting(Route) 包装路由
TanStack Router	tanstackRouterBrowserTracingIntegration(router)	传入路由器实例——无需钩子
无路由器 / 自定义	browserTracingIntegration()	根据 URL 路径命名事务

React Router v6/v7 设置：

// in instrument.ts integrations array:
import React from "react";
import {
  createRoutesFromChildren, matchRoutes,
  useLocation, useNavigationType,
} from "react-router-dom"; // or "react-router" for v7
import * as Sentry from "@sentry/react";
import { reactRouterV6BrowserTracingIntegration } from "@sentry/react";
import { createBrowserRouter } from "react-router-dom";

// Option A — createBrowserRouter (recommended for v6.4+):
const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV6(createBrowserRouter);
const router = sentryCreateBrowserRouter([...routes]);

// Option B — createBrowserRouter for React Router v7:
// const sentryCreateBrowserRouter = Sentry.wrapCreateBrowserRouterV7(createBrowserRouter);

// Option C — integration with hooks (v6 without data APIs):
Sentry.init({
  integrations: [
    reactRouterV6BrowserTracingIntegration({
      useEffect: React.useEffect,
      useLocation,
      useNavigationType,
      matchRoutes,
      createRoutesFromChildren,
    }),
  ],
});

TanStack Router 设置：

import { tanstackRouterBrowserTracingIntegration } from "@sentry/react";

// Pass your TanStack router instance:
Sentry.init({
  integrations: [tanstackRouterBrowserTracingIntegration(router)],
});

Redux 集成（检测到时）

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

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

Source Maps 设置（强烈推荐）

没有 source maps，堆栈跟踪会显示压缩后的代码。设置构建插件以自动上传 source maps：

Vite（vite.config.ts）：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [
    react(),
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

Create React App（通过 CRACO）：

npm install @craco/craco @sentry/webpack-plugin --save-dev

// craco.config.js
const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");

module.exports = {
  webpack: {
    plugins: {
      add: [
        sentryWebpackPlugin({
          org: process.env.SENTRY_ORG,
          project: process.env.SENTRY_PROJECT,
          authToken: process.env.SENTRY_AUTH_TOKEN,
        }),
      ],
    },
  },
};

SENTRY_ORG / SENTRY_PROJECT / SENTRY_AUTH_TOKEN 是构建时的值；身份验证令牌属于机密（切勿提交）。有关创建令牌并将其接入 CI 的说明，请参阅 sentry-source-maps。

对每项已商定的功能

逐项处理功能。加载参考文件，按步骤操作，并在继续之前验证：

功能	参考文档	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终（基线）
跟踪	${SKILL_ROOT}/references/tracing.md	SPA 导航 / API 调用跟踪
会话回放	${SKILL_ROOT}/references/session-replay.md	面向用户的应用
日志记录	${SKILL_ROOT}/references/logging.md	结构化日志搜索 / 日志到跟踪
性能分析	${SKILL_ROOT}/references/profiling.md	性能关键型应用
React 功能	${SKILL_ROOT}/references/react-features.md	Redux、组件跟踪、source maps、集成目录

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证功能正常。

---

配置参考

Sentry.init() 的关键选项

选项	类型	默认值	说明
dsn	string	—	必填。 为空时禁用 SDK
environment	string	"production"	例如，"staging"、"development"
release	string	—	例如，"[email protected]" 或 git SHA — 将错误关联到发布版本
dataCollection	object	未设置时采用保守默认值	精细控制自动收集的数据类别（userInfo、cookies、httpHeaders、httpBodies、queryParams、genAI）。省略此选项时，SDK 会回退到 sendDefaultPii（默认值为 false）。传入该对象（即使是 {}）也会将未设置类别切换为宽松默认值；可按类别选择退出。
tracesSampleRate	number	—	0–1；开发环境使用 1.0，生产环境使用 0.1–0.2
tracesSampler	function	—	按事务采样；优先于采样率
tracePropagationTargets	(string|RegExp)[]	—	接收分布式追踪标头的传出 URL
replaysSessionSampleRate	number	—	录制的所有会话所占比例
replaysOnErrorSampleRate	number	—	录制的错误会话所占比例
enableLogs	boolean	false	启用 Sentry.logger.* API
attachStacktrace	boolean	false	在 captureMessage() 调用中附加堆栈跟踪
maxBreadcrumbs	number	100	每个事件存储的面包屑数量
debug	boolean	false	在控制台输出详细的 SDK 信息
tunnel	string	—	用于绕过广告拦截器的代理 URL

dataCollection 选项（SDK ≥10.57.0）

精细控制 SDK 收集的数据。默认启用数据收集（并会清除敏感值）；可按类别选择退出：

字段	类型	默认值	说明
userInfo	boolean	true	收集用户 ID、邮箱和 IP
cookies	boolean | { allow: string[] } | { deny: string[] }	true	Cookie 收集与筛选；true = 收集所有 Cookie（会筛除敏感键）
httpHeaders.request	boolean | { allow: string[] } | { deny: string[] }	true	收集 HTTP 请求标头
httpHeaders.response	boolean | { allow: string[] } | { deny: string[] }	true	收集 HTTP 响应标头
queryParams	boolean | { allow: string[] } | { deny: string[] }	true	收集和筛选查询参数
httpBodies	HttpBodyCollectionTarget[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	收集请求/响应正文；选项：'incomingRequest'、'outgoingRequest'、'incomingResponse'、'outgoingResponse'
genAI.inputs	boolean	true	记录 AI 模型输入（用于 AI 监控）
genAI.outputs	boolean	true	记录 AI 模型输出（用于 AI 监控）
stackFrameVariables	boolean	true	捕获堆栈帧中的局部变量值
frameContextLines	number	5	堆栈帧周围的源代码上下文行数

示例： 仅允许特定 Cookie 和标头：

Sentry.init({
  dataCollection: {
    cookies: { allow: ['session', 'user_id'] },
    httpHeaders: {
      request: { allow: ['authorization', 'x-request-id'] },
      response: { deny: ['set-cookie'] },
    },
  },
});

React 兼容性矩阵

React 版本	错误处理方式	SDK 最低版本
React 19+	在 createRoot 上使用 reactErrorHandler()	@sentry/react ≥8.0.0
React 16–18	Sentry.ErrorBoundary 组件	@sentry/react ≥7.0.0
React 16	componentDidCatch 类边界	@sentry/react ≥6.0.0

---

验证

触发测试事件，确认 Sentry 正在接收数据：

// Add a temporary test button anywhere in your app
import * as Sentry from "@sentry/react";

function SentryTest() {
  return (
    <>
      <button onClick={() => { throw new Error("Sentry React test error"); }}>
        Test Error
      </button>
      <button onClick={() => Sentry.captureMessage("Sentry test message", "info")}>
        Test Message
      </button>
    </>
  );
}

检查 Sentry 控制面板：

• 问题 → 几秒内出现错误
• 追踪 → 显示页面加载和导航事务
• 回放 → 页面交互后可查看会话录制
• 日志 → 启用日志记录时显示结构化日志条目

如果没有任何内容出现，请在 Sentry.init() 中设置 debug: true，并检查浏览器控制台。

---

第 4 阶段：交叉链接

完成 React 设置后，检查是否存在未配置 Sentry 的配套后端：

ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml 2>/dev/null | grep '<artifactId>' | head -3

如果后端存在但未配置 Sentry，建议使用对应的技能：

检测到的后端	建议的技能
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
Java（pom.xml、build.gradle）	使用 @sentry/java — 参见 docs.sentry.io/platforms/java/
Node.js（Express、Fastify）	使用 @sentry/node — 参见 docs.sentry.io/platforms/javascript/guides/express/

---

故障排查

问题	解决方案
未显示事件	设置 debug: true，检查 DSN，并打开浏览器控制台查看 SDK 错误
Source map 未生效	在生产模式下构建（npm run build）；确认已设置 SENTRY_AUTH_TOKEN
堆栈跟踪被压缩	Source map 未上传 — 检查插件配置和身份验证令牌
instrument.ts 未首先运行	确认它是入口文件中 React/应用导入之前的第一个导入项
未捕获 React 19 错误	确认 reactErrorHandler() 已传入所有三个 createRoot 选项
未捕获 React <19 错误	确保 <Sentry.ErrorBoundary> 包裹组件树
路由器事务名称为 <unknown>	添加与路由器版本匹配的路由器集成
tracePropagationTargets 不匹配	检查正则表达式转义；默认值仅为 localhost 和 DSN 来源
未录制会话回放	确认初始化中包含 replayIntegration()；检查 replaysSessionSampleRate
Redux 操作未出现在面包屑中	将 Sentry.createReduxEnhancer() 添加到 store enhancers
广告拦截器丢弃事件	设置 tunnel: "/sentry-tunnel"，并添加服务端中继端点
会话回放存储成本过高	降低 replaysSessionSampleRate；保持 replaysOnErrorSampleRate: 1.0
性能分析无法运行	确认文档响应中已设置 Document-Policy: js-profiling 标头