在 TanStack Start React 项目中接入…

当需要为 TanStack Start React 应用（浏览器端 + 服务端）完整配置 Sentry SDK 时，按此流程检测项目、安装依赖并逐项启用可观测性功能。

适用场景

解决思路

1. 先运行检测命令了解项目现状：用 `cat package.json | grep -E '"@tanstack/react-start"|"@tanstack/react-router"|"@sentry/tanstackstart-react"'` 确认框架与 SDK 是否已装；用 `cat package.json | grep '"@sentry/'` 检查是否已有 Sentry；用 `ls src/router.tsx src/start.ts src/server.ts instrument.server.mjs vite.config.ts vite.config.js` 检测关键文件；用 `cat .env .env.local .env.sentry-build-plugin | grep "SENTRY_AUTH_TOKEN"` 检查 source map 上传凭据；用 `cat package.json | grep -E '"dev"|"build"|"start"|NODE_OPTIONS|--import'` 检测部署脚本；用 `cat package.json | grep -E '"pino"|"winston"|"loglevel"'` 检测日志库；用 `ls ../backend ../server ../api` 与 `cat ../go.mod ../requirements.txt ../Gemfile ../pom.xml | head -3` 检测配套后端。
2. 根据检测结果给出明确推荐而非开放式提问：核心覆盖为错误监控（始终启用）、Tracing（通常启用）、Session Replay（面向用户的应用推荐）；可选增强为 Logs（需要结构化日志搜索与日志-追踪关联时）与 User Feedback（产品团队需要应用内反馈时）。
3. 安装依赖：`npm install @sentry/tanstackstart-react --save`。
4. 在 `src/router.tsx` 的路由工厂内初始化客户端 Sentry，并用 `if (!router.isServer)` 限定为浏览器端；配置 `dsn`、`dataCollection`、`integrations`（`Sentry.tanstackRouterBrowserTracingIntegration(router)`、`Sentry.replayIntegration()`、`Sentry.feedbackIntegration({ colorScheme: "system" })`）、`enableLogs: true`、`tracesSampleRate: 1.0`、`replaysSessionSampleRate: 0.1`、`replaysOnErrorSampleRate: 1.0`。
5. 在项目根目录创建 `instrument.server.mjs` 并调用 `Sentry.init`，配置 `dsn`、`dataCollection`（如需禁用用户数据与 HTTP body 可取消注释 `userInfo: false` 与 `httpBodies: []`）、`enableLogs: true`、`tracesSampleRate: 1.0`。
6. 在 `vite.config.ts` 中把 `sentryTanstackStart` 作为最后一个插件加入，传入 `org`、`project` 与 `authToken: process.env.SENTRY_AUTH_TOKEN`；若 token 存在 `.env` 中，先用 `loadEnv` 加载再传给插件。
7. 在 `src/server.ts` 中用 `wrapFetchWithSentry` 包裹 fetch handler：`export default createServerEntry(wrapFetchWithSentry({ fetch(request) { return handler.fetch(request); } }))`。
8. 在 `src/start.ts` 中通过 `createStart` 注册全局中间件：`requestMiddleware: [sentryGlobalRequestMiddleware]` 与 `functionMiddleware: [sentryGlobalFunctionMiddleware]`，且 Sentry 中间件必须放在各自数组的第一位。
9. 选择运行时启动方式：优先用 `--import` 标志（可控制 Node 启动参数时，生产监控首选），例如 `"dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000"`、`"build": "vite build && cp instrument.server.mjs .output/server"`、`"start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs"`；若宿主限制启动参数（如 serverless），则在 `src/server.ts` 顶部直接 `import "../instrument.server.mjs"`（仅支持原生 Node API 的插桩）。
10. 对每个已确认的功能逐个处理：读取 `${SKILL_ROOT}/references/<feature>.md`（error-monitoring、tracing、session-replay、logging、user-feedback、tanstackstart-features），严格按步骤执行并在进入下一项前验证生效。
11. 配置关键 `Sentry.init()` 选项：`dsn`（必填，为空则 SDK 禁用）、`dataCollection`（细粒度控制 `userInfo`、`cookies`、`httpHeaders`、`httpBodies`、`queryParams`、`genAI`；省略时回退到 `sendDefaultPii` 默认 false，传入对象即使为 `{}` 也会把未设置类别翻转为宽松默认值）、`integrations`、`enableLogs`、`tracesSampleRate`、`replaysSessionSampleRate`、`replaysOnErrorSampleRate`、`tunnel`、`debug`。
12. 使用 TanStack Start 专属 API：`tanstackRouterBrowserTracingIntegration(router)` 做浏览器导航追踪；`wrapFetchWithSentry(...)` 做服务端请求追踪与错误捕获；`sentryGlobalRequestMiddleware` 捕获请求级服务端错误；`sentryGlobalFunctionMiddleware` 捕获服务端函数错误；`sentryTanstackStart({...})` 作为 Vite 插件处理 source map 与中间件插桩。
13. 验证：前端用按钮抛出 `new Error("Sentry Test Error")` 测试 Issues；用 `Sentry.startSpan({ name: "Example Frontend Span", op: "test" }, ...)` 包裹 `fetch("/api/sentry-example")` 测试前后端 Tracing；用 `Sentry.logger.info/warn/error` 测试 Logs；随后在 Sentry 中确认 Issues、Traces、Replays、Logs、User Feedback 均收到数据。
14. 完成后做交叉链接：用 `ls ../backend ../server ../api ../go ../python` 与 `cat ../go.mod ../requirements.txt ../pyproject.toml ../Gemfile ../pom.xml | head -5` 检查是否存在未接入 Sentry 的配套后端，并按语言推荐对应技能（Go→`sentry-go-sdk`、Python→`sentry-python-sdk`、Ruby→`sentry-ruby-sdk`、Java→`@sentry/java` 文档、Node 后端→`sentry-node-sdk`）。
15. 排障：事件不出现时设 `debug: true`、核对 DSN 并确认客户端与服务端初始化文件都执行；无服务端追踪时确认 `src/server.ts` 用了 `wrapFetchWithSentry` 且运行时加载了 `instrument.server.mjs`；路由处理器服务端错误缺失时确认两个全局中间件在数组首位；source map 不解析时核对 `SENTRY_AUTH_TOKEN`、`org`、`project`；Vite 配置中 token 为 undefined 时用 `loadEnv(mode, process.cwd(), "")` 或 `.env.sentry-build-plugin`；Replay 不录制时确认 `replayIntegration()` 已加入且采样率非零；Feedback 不显示时确认 `feedbackIntegration()` 已配置并检查 CSS z-index 冲突；Logs 缺失时设 `enableLogs: true` 并使用 `Sentry.logger.*`；直接 import 方式缺少库 span 时尽量改用 `--import`；SSR 渲染异常未被自动捕获时在错误边界/回退处理器中手动 `Sentry.captureException`。

适用边界 · 注意事项

• 该 SDK 目前为 alpha，仅文档声明兼容 TanStack Start 1.0 RC，实施前必须对照官方文档 docs.sentry.io/platforms/javascript/guides/tanstackstart-react/ 核实。
• 项目未使用 TanStack Start React（缺少 `@tanstack/react-start`）时不适用此流程。
• 宿主环境既不允许控制 Node 启动参数、又需要库级自动插桩时，直接 import 方案只能覆盖原生 Node API，效果受限。