在 React Router v7 Framework…

当需要为 React Router Framework 模式（v7，使用 entry.client.tsx / entry.server.tsx）项目安装并配置 @sentry/react-router，实现客户端与服务端错误监控、追踪、性能分析、会话回放、日志和用户反馈时使用。

适用场景

解决思路

1. Phase 1 检测：运行命令检查 package.json 中是否已有 react-router、@react-router/、react-router-dev、react-router-serve，以及 @sentry/react-router、@sentry/react、@sentry/profiling-node；检查 entry.client.tsx、entry.server.tsx、instrument.server.mjs、react-router.config.ts、vite.config.ts 是否存在；检查 dev/start 脚本是否含 NODE_OPTIONS 或 --import；检查 pino/winston/@sentry/profiling-node 等可选依赖；检查 ../backend、../server、../api 等后端目录及 go.mod/requirements.txt/Gemfile/pom.xml。据此判断：是否已装 SDK、入口文件是否已暴露、是否误用 @sentry/react（非 framework 模式应改用 sentry-react-sdk）、是否有 Vite 配置、是否可用 NODE_OPTIONS --import、是否需要 profiling、是否有后端可交叉链接。
2. Phase 2 推荐：默认推荐错误监控（始终）+ 追踪（framework 应用通常推荐）+ 会话回放（面向用户产品）；可选性能分析（服务端性能排查且 Node 兼容）、日志（需要日志检索与 trace 关联）、用户反馈（产品/支持团队需要应用内反馈）。以提案形式给出，例如“建议先启用错误监控+追踪+会话回放，是否还要启用性能分析、日志和用户反馈？”。
3. Phase 3 方式一（推荐向导）：让用户自行运行交互式向导 npx @sentry/wizard@latest -i reactRouter，它会安装 @sentry/react-router、暴露入口文件、创建 instrumentation 文件、更新根错误处理、配置 source map 上传并添加验证示例；完成后跳到验证步骤。
4. Phase 3 方式二（手动安装）：运行 npm install @sentry/react-router --save；如需性能分析再运行 npm install @sentry/profiling-node --save。
5. 暴露 framework 入口文件：运行 npx react-router reveal。
6. 配置客户端 entry.client.tsx：从 @sentry/react-router 导入 Sentry，调用 Sentry.init 设置 dsn、dataCollection（可注释 userInfo:false 与 httpBodies:[] 以禁用用户数据与 HTTP body）、integrations 包含 Sentry.reactRouterTracingIntegration()、Sentry.replayIntegration()、Sentry.feedbackIntegration({ colorScheme: "system" })，设置 enableLogs: true、tracesSampleRate: 1.0、tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/]、replaysSessionSampleRate: 0.1、replaysOnErrorSampleRate: 1.0；在 startTransition 中 hydrateRoot 渲染 <StrictMode><HydratedRouter onError={Sentry.sentryOnError} /></StrictMode>。
7. 配置服务端 instrument.server.mjs：从 @sentry/react-router 导入 Sentry，从 @sentry/profiling-node 导入 nodeProfilingIntegration，调用 Sentry.init 设置 dsn、dataCollection、enableLogs: true、integrations: [nodeProfilingIntegration()]、tracesSampleRate: 1.0、profileSessionSampleRate: 1.0。
8. 包装服务端 entry.server.tsx：使用 Sentry.createSentryHandleRequest({ ServerRouter, renderToPipeableStream, createReadableStreamFromReadable }) 作为默认导出，使用 Sentry.createSentryHandleError({ logErrors: false }) 作为 handleError；自定义服务端逻辑时使用 wrapSentryHandleRequest、getMetaTagTransformer 并在自定义 handleError 中手动 Sentry.captureException。
9. 启动时加载服务端 instrumentation：优先在 package.json 脚本中使用 NODE_OPTIONS='--import ./instrument.server.mjs'（dev 与 start 均如此）；在运行时标志受限的平台上回退为在代码中直接 import "./instrument.server.mjs"（注意此方式自动 instrumentation 可能不完整）。
10. 配置 source maps：在 vite.config.ts 中导入 reactRouter、sentryReactRouter 与 SentryReactRouterBuildOptions，定义 sentryConfig（org、project、authToken: process.env.SENTRY_AUTH_TOKEN），在 plugins 中加入 reactRouter() 与 sentryReactRouter(sentryConfig, config)；在 react-router.config.ts 中设置 ssr: true 并在 buildEnd 中调用 sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest })。
11. 按已同意的功能逐项配置：每次加载 ${SKILL_ROOT}/references/<feature>.md 并严格按步骤执行、验证后再进入下一项。对应关系：错误监控→error-monitoring.md（始终）、追踪→tracing.md、性能分析→profiling.md、会话回放→session-replay.md、日志→logging.md、用户反馈→user-feedback.md、框架特性（入口文件、包装器、source maps、启动导入策略）→react-router-framework-features.md。
12. 配置参考：Sentry.init 关键选项包括 dsn（必填，为空则 SDK 禁用）、dataCollection（userInfo 默认 true、cookies 默认 true、httpHeaders 默认 { request: true, response: true }）、sendDefaultPii（已废弃，v11 移除，改用 dataCollection）、integrations、enableLogs（默认 false）、tracesSampleRate、tracePropagationTargets、replaysSessionSampleRate、replaysOnErrorSampleRate、profileSessionSampleRate、tunnel、debug。
13. 框架专用 API：reactRouterTracingIntegration()（客户端追踪）、sentryOnError（HydratedRouter 错误上报）、createSentryHandleRequest(...)（服务端请求包装）、createSentryHandleError(...)（服务端错误处理包装）、wrapServerLoader(...)/wrapServerAction(...)（手动包装 loader/action）、sentryReactRouter(...)（Vite 插件）、sentryOnBuildEnd(...)（构建结束钩子处理 source map）。
14. 验证：若向导生成了示例，打开 /sentry-example-page 触发测试操作；手动错误测试可在 loader 中 throw new Error("My first Sentry error!")；手动追踪测试用 Sentry.startSpan({ op: "test", name: "My First Test Transaction" }, () => { throw new Error("My first Sentry error!") })；日志测试用 Sentry.logger.info/warn/error 记录。在 Sentry 中确认 Issues、Traces、Profiles、Replays、Logs、User Feedback 均出现对应数据。
15. Phase 4 交叉链接：确认应用是否实际为非 framework 路由（v5/v6/v7 data/declarative 且使用 @sentry/react），若是则改用 sentry-react-sdk；再检查 ../backend、../server、../api、../go、../python 及 go.mod/requirements.txt/pyproject.toml/Gemfile/pom.xml，按后端语言建议 sentry-go-sdk、sentry-python-sdk、sentry-ruby-sdk、sentry-node-sdk 或 @sentry/java 文档。
16. 故障排查：入口文件缺失先运行 npx react-router reveal；客户端错误缺失检查 HydratedRouter 是否含 onError={Sentry.sentryOnError}；服务端错误缺失检查是否使用 createSentryHandleRequest 与 createSentryHandleError；自定义服务端处理器绕过 Sentry 时改用 wrapSentryHandleRequest 并手动 captureException；source map 未上传检查 sentryReactRouter 插件与 sentryOnBuildEnd；SENTRY_AUTH_TOKEN 未定义时在配置中加载环境变量或使用 .env.sentry-build-plugin；服务端自动 instrumentation 不完整时优先用 NODE_OPTIONS='--import ./instrument.server.mjs'；性能数据缺失确认已装 @sentry/profiling-node 并启用 nodeProfilingIntegration；Node 自动 instrumentation 版本不支持时改用 instrumentation API/手动包装；非 framework 应用误用 @sentry/react-router 时改用 sentry-react-sdk + @sentry/react。

适用边界 · 注意事项

• React Router 非 framework/data/declarative 模式（v5/v6/v7）应使用 sentry-react-sdk 与 @sentry/react，而非本技能。
• 该 SDK 目前处于 beta 阶段，对稳定性要求极高的生产环境需谨慎评估。
• 需要先安装 @sentry/react-router 并暴露 framework 入口文件（entry.client.tsx / entry.server.tsx），否则无法按本流程配置。