用途
Sentry React SDK 用于为 React 应用接入 Sentry 的错误监控与可观测性能力。当用户提出「给 React 加上 Sentry」「安装 @sentry/react」，或需要配置错误监控、Tracing、Session Replay、Profiling、日志，以及监控 React Router 导航、Redux 状态或组件性能时，可使用本技能。
该技能是一套有明确主张的配置向导，会先扫描项目再给出完整接入方案。文档注明的 SDK 版本与 API 反映的是撰写时的 Sentry 文档（@sentry/react ≥8.0.0），实施前需以 docs.sentry.io 为准。
阶段一：检测
先运行命令了解项目，再提出任何建议。需检测的内容包括：React 版本（"react"/"react-dom"）、是否已存在 Sentry（"@sentry/）、路由（react-router-dom、@tanstack/react-router）、状态管理（redux、@reduxjs/toolkit）、构建工具（vite.config、webpack.config、craco.config，以及 vite/react-scripts/webpack）、日志库（pino/winston/loglevel），并检查相邻目录中是否存在配套后端（../backend、../server、../api，以及 go.mod、requirements.txt、Gemfile、pom.xml）。
判定影响：React 19+ 使用 reactErrorHandler() hook 模式；React <19 使用 Sentry.ErrorBoundary；已有 @sentry/react 则跳过安装直接配置功能；react-router-dom v5/v6/v7 决定使用哪个路由集成；@tanstack/react-router 使用 tanstackRouterBrowserTracingIntegration()；使用 Redux 则推荐 createReduxEnhancer()；检测到 Vite 则通过 sentryVitePlugin 处理源码映射；CRA（react-scripts）则通过 CRACO 中的 @sentry/webpack-plugin 处理源码映射；发现后端目录则触发阶段四的交叉联动建议。
阶段二：推荐
基于检测结果给出具体建议，而不是开放式提问。
推荐（核心覆盖）：错误监控——始终启用，捕获未处理错误、React 错误边界与 React 19 hooks；Tracing——React SPA 受益于页面加载、导航与 API 调用追踪；Session Replay——推荐给面向用户的应用，围绕错误录制会话。
可选（增强可观测性）：Logging——通过 Sentry.logger.* 输出结构化日志，需要结构化日志搜索时推荐；Profiling——JS Self-Profiling API（⚠️ 实验性；需要跨源隔离响应头）。
React 专属附加项：检测到 React 19 → 在 createRoot 上设置 reactErrorHandler()；检测到 React Router → 配置匹配的路由集成；检测到 Redux → 为 store 添加 createReduxEnhancer()；检测到 Vite → 配置 sentryVitePlugin 处理源码映射（对可读堆栈至关重要）。
阶段三：配置指引
安装：npm install @sentry/react --save
创建 src/instrument.ts：Sentry 必须在其他任何代码运行前初始化，因此将 Sentry.init() 放在独立的侧车文件中。文档给出的示例配置包含：dsn、environment、release、sendDefaultPii、integrations（browserTracingIntegration、replayIntegration，并设置 maskAllText 与 blockAllMedia）、tracesSampleRate、tracePropagationTargets、replaysSessionSampleRate、replaysOnErrorSampleRate、enableLogs。
DSN 环境变量按构建工具区分：Vite 使用 VITE_SENTRY_DSN / import.meta.env.VITE_SENTRY_DSN；CRA 使用 REACT_APP_SENTRY_DSN / process.env.REACT_APP_SENTRY_DSN；自定义 webpack 使用 SENTRY_DSN / process.env.SENTRY_DSN。
入口点设置：在入口文件（Vite 为 src/main.tsx，CRA/webpack 为 src/index.tsx）中，必须将 import "./instrument"; 作为第一个 import。
按 React 版本处理错误：React 19+ 在 createRoot 中为 onUncaughtError、onCaughtError、onRecoverableError 传入 reactErrorHandler()；React <19 用 <Sentry.ErrorBoundary> 包裹应用（可带 fallback 与 showDialog）；任何需要独立捕获错误的子树（路由区块、组件等）也可使用 <Sentry.ErrorBoundary>。
路由集成：React Router v7 使用 reactRouterV7BrowserTracingIntegration；v6 使用 reactRouterV6BrowserTracingIntegration；v5 使用 reactRouterV5BrowserTracingIntegration（用 withSentryRouting(Route) 包裹路由）；TanStack Router 使用 tanstackRouterBrowserTracingIntegration(router)，直接传入 router 实例；无路由或自定义路由使用 browserTracingIntegration()，按 URL 路径命名事务。React Router v6/v7 提供多种方式，如 wrapCreateBrowserRouterV6/V7 包裹 createBrowserRouter，或使用带 hooks 的集成配置。
Redux 集成：在使用 @reduxjs/toolkit 的 configureStore 中，通过 enhancers 追加 Sentry.createReduxEnhancer()。
源码映射设置（强烈推荐）：没有源码映射时堆栈显示的是压缩代码。Vite 中在 vite.config.ts 配置 build.sourcemap 为 "hidden" 并加入 sentryVitePlugin（org、project、authToken）；CRA 需安装 @craco/craco @sentry/webpack-plugin 并在 craco.config.js 中配置 sentryWebpackPlugin。.env 中需设置 SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT 且不要提交。
按已确认的功能逐项推进：每个功能一次，加载对应参考文件并遵循步骤，验证后再继续。参考文件包括：error-monitoring.md（始终，基线）、tracing.md（SPA 导航/API 调用追踪）、session-replay.md（面向用户的应用）、logging.md（结构化日志搜索/日志到追踪）、profiling.md（性能关键应用）、react-features.md（Redux、组件追踪、源码映射、集成目录）。
配置参考要点
Sentry.init() 主要选项：dsn（必填，为空时 SDK 禁用）、environment（默认 "production"）、release（如 "my-app@1.0.0" 或 git SHA）、sendDefaultPii（默认 false，包含 IP 与请求头）、tracesSampleRate（0–1；开发 1.0，生产 0.1–0.2）、tracesSampler（按事务采样，覆盖 rate）、tracePropagationTargets（接收分布式追踪头的出站 URL）、replaysSessionSampleRate、replaysOnErrorSampleRate、enableLogs（默认 false，启用 Sentry.logger.*）、attachStacktrace、maxBreadcrumbs（默认 100）、debug（默认 false）、tunnel（绕过广告拦截器的代理 URL）。
React 兼容性矩阵：React 19+ 使用 reactErrorHandler()，SDK 最低 @sentry/react ≥8.0.0；React 16–18 使用 Sentry.ErrorBoundary 组件，SDK ≥7.0.0；React 16 使用 componentDidCatch 类边界，SDK ≥6.0.0。
验证
通过触发测试事件确认 Sentry 收到数据，例如临时添加按钮抛出错误或调用 Sentry.captureMessage。在 Sentry 控制台检查 Issues（错误）、Traces（页面加载与导航事务）、Replays（会话录制）、Logs（结构化日志）。若没有任何数据，在 Sentry.init() 中设置 debug: true 并查看浏览器控制台。
阶段四：交叉联动
完成 React 配置后，检查是否存在尚未接入 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；Node.js（Express、Fastify）→ 使用 @sentry/node。
常见问题排查
事件未出现：设 debug: true，检查 DSN 与控制台；源码映射无效：以生产模式构建并确认 SENTRY_AUTH_TOKEN；堆栈被压缩：源码映射未上传；instrument.ts 未最先运行：确认是入口首个 import；React 19 错误未捕获：确认三个 createRoot 选项都传了 reactErrorHandler()；React <19 未捕获：确认 ErrorBoundary 包裹了组件树；路由事务名称为 <unknown>：添加匹配版本的路由集成；tracePropagationTargets 不匹配：检查正则转义；会话回放未录制：确认 init 中有 replayIntegration() 并检查采样率；Redux 动作未出现在面包屑：添加 createReduxEnhancer()；广告拦截器丢弃事件：设置 tunnel 并添加服务端中继端点；回放存储成本过高：降低 replaysSessionSampleRate，保持 replaysOnErrorSampleRate 为 1.0；Profiling 不工作：确认文档响应设置了 Document-Policy: js-profiling 头。