sentry-react-router-framework-sdk

所有技能 > SDK 设置 > React Router Framework SDK

Sentry React Router Framework SDK

一款集成向导，可扫描 React Router Framework 项目，并指导你在客户端和服务端入口文件中完成 Sentry 设置。

适用场景

• 用户要求“将 Sentry 添加到 React Router Framework”或“在 React Router v7 framework mode 中设置 Sentry”
• 用户希望安装或配置 @sentry/react-router
• 用户使用 React Router framework 入口文件（entry.client.tsx、entry.server.tsx），并希望捕获追踪信息和错误
• 用户询问 reactRouterTracingIntegration、sentryOnError、createSentryHandleRequest 或 React Router 向导设置

重要： 此 SDK 目前处于 beta 阶段。 对于 React Router 非 framework/data/declarative 模式（v5/v6/v7），请改用 sentry-react-sdk 和 @sentry/react 集成。

---

第 1 阶段：检测

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

# Detect React Router Framework indicators and versions
cat package.json | grep -E '"react-router"|"@react-router/"|"react-router-dev"|"react-router-serve"'

# Detect Sentry package choice
cat package.json | grep -E '"@sentry/react-router"|"@sentry/react"|"@sentry/profiling-node"'

# Check entry point visibility and server instrumentation files
ls entry.client.tsx entry.server.tsx instrument.server.mjs react-router.config.ts vite.config.ts 2>/dev/null

# Check if React Router files are still hidden (framework mode helper command available)
cat package.json | grep -E '"reveal"|react-router'

# Detect runtime startup scripts and import strategy
cat package.json | grep -E '"dev"|"start"|NODE_OPTIONS|--import'

# Detect optional logging/profile-related dependencies
cat package.json | grep -E '"pino"|"winston"|"@sentry/profiling-node"'

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

需要确定的事项：

问题	影响
是否已安装 @sentry/react-router？	跳过安装，继续设置功能
是否已公开 framework 入口文件？	手动配置前需要运行 npx react-router reveal
是否改用 @sentry/react？	这很可能是非 framework 路由；请引导用户使用 sentry-react-sdk
是否存在 react-router.config.ts 和 Vite 配置？	确定 Source Map 上传及构建结束钩子的设置路径
是否可用 NODE_OPTIONS --import？	服务端检测的首选启动方式
是否需要或可用 @sentry/profiling-node？	启用服务端性能分析集成
是否找到了后端目录？	触发第 4 阶段的交叉链接建议

---

第 2 阶段：提出建议

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

推荐（核心覆盖）：

• ✅ 错误监控 — 始终启用；通过 framework 钩子捕获客户端和服务端错误
• ✅ 追踪 — framework 应用的推荐基线，适用于客户端/服务端请求流程
• ✅ 会话回放 — 推荐用于面向用户的应用

可选（增强可观测性）：

• ⚡ 性能分析 — 使用 @sentry/profiling-node 进行服务端性能分析
• ⚡ 日志 — 结构化 Sentry.logger.* 数据接入与关联
• ⚡ 用户反馈 — 应用内反馈小组件和报告流程

建议逻辑：

功能	建议启用的情况……
错误监控	始终启用 — 不可妥协的基线
追踪	framework 应用中通常建议启用；路由和请求耗时具有很高的价值
会话回放	面向用户的产品，或难以调试的用户体验问题
性能分析	需要调查服务端性能问题；已验证与 Node 运行时兼容
日志	团队希望在 Sentry 中搜索日志并关联追踪
用户反馈	产品/支持团队需要直接收集应用内问题报告

建议：“我建议先启用错误监控、追踪和会话回放。要我同时启用性能分析、日志和用户反馈吗？”

---

第 3 阶段：引导设置

选项 1：向导（推荐）

你需要自行运行此命令 — 向导为交互式流程，可能需要通过浏览器登录：

npx @sentry/wizard@latest -i reactRouter

它会安装 @sentry/react-router、公开 React Router 入口文件、创建检测文件、更新根错误处理、配置 Source Map 上传，并添加验证示例。

完成后，请继续查看验证。

如果用户跳过向导设置，请继续进行以下手动设置。

---

选项 2：手动设置

安装软件包

npm install @sentry/react-router --save

如果需要性能分析：

npm install @sentry/profiling-node --save

公开 framework 入口文件

npx react-router reveal

在 entry.client.tsx 中配置客户端

import * as Sentry from "@sentry/react-router";
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  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-router/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  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(
    document,
    <StrictMode>
      <HydratedRouter onError={Sentry.sentryOnError} />
    </StrictMode>,
  );
});

在 instrument.server.mjs 中配置服务端

import * as Sentry from "@sentry/react-router";
import { nodeProfilingIntegration } from "@sentry/profiling-node";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  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-router/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  enableLogs: true,
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
});

在 entry.server.tsx 中封装服务器处理程序

import * as Sentry from "@sentry/react-router";
import { createReadableStreamFromReadable } from "@react-router/node";
import { renderToPipeableStream } from "react-dom/server";
import { ServerRouter } from "react-router";

const handleRequest = Sentry.createSentryHandleRequest({
  ServerRouter,
  renderToPipeableStream,
  createReadableStreamFromReadable,
});

export default handleRequest;

export const handleError = Sentry.createSentryHandleError({
  logErrors: false,
});

对于自定义服务器逻辑，请在自定义 handleError 中使用 wrapSentryHandleRequest、getMetaTagTransformer 和手动调用 Sentry.captureException。

在启动时加载服务器插桩

优先使用 NODE_OPTIONS --import：

{
  "scripts": {
    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router dev",
    "start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js"
  }
}

对于运行时标志受限的平台，可使用以下回退方案：

import "./instrument.server.mjs";

与 --import 相比，这种直接导入方法可能导致自动插桩不完整。

配置源映射

vite.config.ts：

import { reactRouter } from "@react-router/dev/vite";
import {
  sentryReactRouter,
  type SentryReactRouterBuildOptions,
} from "@sentry/react-router";
import { defineConfig } from "vite";

const sentryConfig: SentryReactRouterBuildOptions = {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",
  authToken: process.env.SENTRY_AUTH_TOKEN,
};

export default defineConfig((config) => {
  return {
    plugins: [reactRouter(), sentryReactRouter(sentryConfig, config)],
  };
});

react-router.config.ts：

import type { Config } from "@react-router/dev/config";
import { sentryOnBuildEnd } from "@sentry/react-router";

export default {
  ssr: true,
  buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
    await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest });
  },
} satisfies Config;

---

针对每项已商定的功能

逐项检查功能。加载参考文件，严格按照步骤操作，并在继续之前进行验证：

功能	参考文件	加载时机
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终加载
跟踪	${SKILL_ROOT}/references/tracing.md	需要查看路由／请求性能时
性能分析	${SKILL_ROOT}/references/profiling.md	需要分析服务器性能时
会话回放	${SKILL_ROOT}/references/session-replay.md	面向用户的应用
日志	${SKILL_ROOT}/references/logging.md	需要结构化日志／关联信息时
用户反馈	${SKILL_ROOT}/references/user-feedback.md	需要应用内反馈流程时
框架功能	${SKILL_ROOT}/references/react-router-framework-features.md	涉及入口文件、封装器、源映射或启动导入策略时

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

---

配置参考

Sentry.init() 的关键选项

选项	类型	默认值	说明
dsn	string	—	必填；为空时 SDK 将被禁用
dataCollection	object	—	控制收集哪些数据（userInfo、cookies、httpHeaders 等）
dataCollection.userInfo	boolean	true	包含根据 IP 推断的用户上下文
dataCollection.cookies	CollectBehavior	true	控制 Cookie 的收集和筛选
dataCollection.httpHeaders	object	{ request: true, response: true }	控制 HTTP 标头的收集
sendDefaultPii	boolean	false	已弃用： 请改用 dataCollection；将在 v11 中移除
integrations	Integration[]	SDK 默认值	添加跟踪／回放／反馈／性能分析集成
enableLogs	boolean	false	启用 Sentry.logger.* 数据接收
tracesSampleRate	number	—	测试时通常设为 1.0，生产环境中设得更低
tracePropagationTargets	`(string	RegExp)[]`	SDK 默认值
replaysSessionSampleRate	number	—	录制的所有会话所占比例
replaysOnErrorSampleRate	number	—	录制的错误会话所占比例
profileSessionSampleRate	number	—	进行性能分析的事务所占比例（服务器性能分析）
tunnel	string	—	可选的广告拦截器绕过端点
debug	boolean	false	输出详细的 SDK 诊断信息

框架专用 API

API	用途
reactRouterTracingIntegration()	框架模式下的客户端跟踪集成
sentryOnError	接入 React Router HydratedRouter 错误报告
createSentryHandleRequest(...)	用于框架服务器入口的服务器请求封装器
createSentryHandleError(...)	服务器错误处理程序封装器
wrapServerLoader(...) / wrapServerAction(...)	手动封装服务器 loader／action
sentryReactRouter(...)	用于源映射／构建集成的 Vite 插件
sentryOnBuildEnd(...)	用于处理源映射的 React Router 构建结束钩子

---

验证

向导生成的路径

如果已生成向导示例，请打开 /sentry-example-page 并触发测试操作。

手动错误测试

export async function loader() {
  throw new Error("My first Sentry error!");
}

手动跟踪测试

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

export async function loader() {
  return Sentry.startSpan(
    { op: "test", name: "My First Test Transaction" },
    () => {
      throw new Error("My first Sentry error!");
    },
  );
}

日志测试

Sentry.logger.info("User example action completed");
Sentry.logger.warn("Slow operation detected", { operation: "data_fetch", duration: 3500 });
Sentry.logger.error("Validation failed", { field: "email", reason: "Invalid email" });

在 Sentry 中确认：

• 问题：出现错误
• 追踪：出现事务／跨度数据
• 性能分析：启用性能分析时出现性能分析数据
• 回放：启用回放时出现回放条目
• 日志：enableLogs: true 时出现日志事件
• 用户反馈：启用反馈时出现提交内容

---

第 4 阶段：交叉链接

完成 React Router Framework 设置后：

1. 检查应用是否实际上使用非框架路由（v5/v6/v7 数据／声明式路由，并使用 @sentry/react）。
2. 如果是，则跳转到 sentry-react-sdk，了解非框架路由集成。

然后检查配套后端的覆盖情况：

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

检测到的后端	建议的技能
Go	sentry-go-sdk
Python	sentry-python-sdk
Ruby	sentry-ruby-sdk
Node 后端服务	sentry-node-sdk
Java 服务	使用 @sentry/java 文档

---

故障排除

问题	解决方案
缺少 entry.client.tsx / entry.server.tsx	先运行 npx react-router reveal
缺少客户端错误	确保 HydratedRouter 包含 onError={Sentry.sentryOnError}
缺少服务器错误	使用 createSentryHandleRequest 和 createSentryHandleError 包装器
自定义服务器处理程序绕过了 Sentry	使用 wrapSentryHandleRequest，并在自定义 handleError 中手动调用 captureException
未上传源映射	检查 sentryReactRouter 插件配置和 sentryOnBuildEnd 钩子
Vite 配置中的 SENTRY_AUTH_TOKEN 未定义	在配置中加载环境变量，或使用 .env.sentry-build-plugin
服务器自动插桩不完整	启动时优先使用 NODE_OPTIONS='--import ./instrument.server.mjs'
缺少性能分析数据	确认已安装 @sentry/profiling-node，并已启用 nodeProfilingIntegration
运行不受支持的 Node 自动插桩版本	按文档所述使用插桩 API／手动包装器
为非框架应用配置了 @sentry/react-router	对于 v5/v6/v7 非框架路由，改用 sentry-react-sdk + @sentry/react