sentry-tanstack-start-sdk

所有技能 > SDK 设置 > TanStack Start React SDK

Sentry TanStack Start React SDK

这款向导风格的工具会扫描你的 TanStack Start React 项目，并引导你完成浏览器和服务器运行时的 Sentry 设置。

适用场景

• 用户要求“将 Sentry 添加到 TanStack Start”或“在 TanStack Start React 应用中设置 Sentry”
• 用户想要安装或配置 @sentry/tanstackstart-react
• 用户想要为 TanStack Start React 配置错误监控、追踪、会话回放、日志或用户反馈
• 用户询问 sentryTanstackStart、wrapFetchWithSentry、instrument.server.mjs 或 TanStack Start 中间件插桩

**注意：**此 SDK 目前处于 alpha 阶段，文档注明其兼容 TanStack Start 1.0 RC。 实施前，请务必对照 docs.sentry.io/platforms/javascript/guides/tanstackstart-react/ 进行核实。

---

阶段 1：检测

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

# Detect TanStack Start / Router and existing Sentry
cat package.json | grep -E '"@tanstack/react-start"|"@tanstack/react-router"|"@sentry/tanstackstart-react"'

# Check if Sentry is already present
cat package.json | grep '"@sentry/'

# Detect key files used by the TanStack Start setup
ls src/router.tsx src/start.ts src/server.ts instrument.server.mjs vite.config.ts vite.config.js 2>/dev/null

# Check whether source map upload credentials are configured
cat .env .env.local .env.sentry-build-plugin 2>/dev/null | grep "SENTRY_AUTH_TOKEN"

# Detect deployment hints in scripts
cat package.json | grep -E '"dev"|"build"|"start"|NODE_OPTIONS|--import'

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

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

需要确定的事项：

问题	影响
是否存在 @tanstack/react-start？	确认此技能是正确的设置路径
是否已安装 @sentry/tanstackstart-react？	跳过安装，直接进行功能调整
是否存在 src/router.tsx？	决定客户端 Sentry.init 的位置
是否存在 src/start.ts？	设置服务器端错误的全局中间件
是否存在 src/server.ts？	决定服务器入口插桩的位置
是否存在 instrument.server.mjs？	确定运行时启动插桩路径
是否存在 vite.config.ts？	添加 sentryTanstackStart 插件和源映射
是否已配置 SENTRY_AUTH_TOKEN？	确认是否已准备好上传源映射
是否找到了后端目录？	触发阶段 4 的交叉链接建议

---

阶段 2：建议

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

推荐（核心覆盖）：

• ✅ 错误监控 — 始终启用；捕获未处理的客户端和服务器错误
• ✅ 追踪 — 对浏览器和服务器的请求及路由耗时进行追踪，价值很高
• ✅ 会话回放 — 推荐用于面向用户的应用

可选（增强可观测性）：

• ⚡ 日志 — 需要结构化日志搜索以及日志与追踪关联时推荐启用
• ⚡ 用户反馈 — 产品团队希望用户在应用内提交问题报告时推荐启用

建议逻辑：

功能	推荐条件
错误监控	始终启用 — 不可或缺的基线功能
追踪	通常推荐用于 TanStack Start；路由和 fetch 插桩可立即带来价值
会话回放	面向用户的应用、登录流程、结账流程，或难以复现的 UX 问题
日志	已有日志策略、支持工作流，或需要关联追踪与日志
用户反馈	团队希望直接收集用户报告，且无需用户离开应用

建议：“我推荐启用错误监控 + 追踪 + 会话回放。需要我也启用日志和用户反馈吗？”

---

阶段 3：引导设置

安装

npm install @sentry/tanstackstart-react --save

在 src/router.tsx 中配置客户端 Sentry

在路由器工厂内初始化 Sentry，并将其限制为仅在浏览器中运行：

import * as Sentry from "@sentry/tanstackstart-react";
import { createRouter } from "@tanstack/react-router";

export const getRouter = () => {
  const router = createRouter();

  if (!router.isServer) {
    Sentry.init({
      dsn: "___PUBLIC_DSN___",
      dataCollection: {
        // userInfo: false,
        // httpBodies: [],
      },

      integrations: [
        Sentry.tanstackRouterBrowserTracingIntegration(router),
        Sentry.replayIntegration(),
        Sentry.feedbackIntegration({
          colorScheme: "system",
        }),
      ],

      enableLogs: true,
      tracesSampleRate: 1.0,
      replaysSessionSampleRate: 0.1,
      replaysOnErrorSampleRate: 1.0,
    });
  }

  return router;
};

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

在项目根目录创建 instrument.server.mjs：

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

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/tanstackstart-react/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  enableLogs: true,
  tracesSampleRate: 1.0,
});

在 vite.config.ts 中配置 Vite 插件

sentryTanstackStart 应作为最后一个插件：

import { defineConfig } from "vite";
import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";

export default defineConfig({
  plugins: [
    tanstackStart(),
    sentryTanstackStart({
      org: "___ORG_SLUG___",
      project: "___PROJECT_SLUG___",
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

如果令牌存储在 .env 中，请先在 Vite 配置中使用 loadEnv 加载，再将其传递给插件。

在 src/server.ts 中插桩服务器入口点

使用 wrapFetchWithSentry 封装 fetch 处理程序：

import { wrapFetchWithSentry } from "@sentry/tanstackstart-react";
import handler, { createServerEntry } from "@tanstack/react-start/server-entry";

export default createServerEntry(
  wrapFetchWithSentry({
    fetch(request: Request) {
      return handler.fetch(request);
    },
  }),
);

在 src/start.ts 中添加全局服务器中间件

这些中间件会捕获服务器端请求和函数错误：

import {
  sentryGlobalFunctionMiddleware,
  sentryGlobalRequestMiddleware,
} from "@sentry/tanstackstart-react";
import { createStart } from "@tanstack/react-start";

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [sentryGlobalRequestMiddleware],
    functionMiddleware: [sentryGlobalFunctionMiddleware],
  };
});

Sentry 中间件应位于每个数组的首位。

运行时启动模式

选择一种运行时方式：

运行时模式	适用场景……	备注
--import 标志	你可以控制 Node 启动标志	生产环境监控的首选方式
在 src/server.ts 中直接导入	宿主环境限制启动标志（例如无服务器宿主）	仅限于对原生 Node API 进行插桩

--import 示例：

{
  "scripts": {
    "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"
  }
}

直接导入回退方案（位于 src/server.ts 顶部）：

import "../instrument.server.mjs";

对每项已商定的功能

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

功能	参考文件	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终加载
跟踪	${SKILL_ROOT}/references/tracing.md	需要查看路由/API 性能时
会话回放	${SKILL_ROOT}/references/session-replay.md	面向用户的应用
日志	${SKILL_ROOT}/references/logging.md	需要结构化日志和关联信息时
用户反馈	${SKILL_ROOT}/references/user-feedback.md	需要收集应用内反馈时
TanStack Start 功能	${SKILL_ROOT}/references/tanstackstart-features.md	涉及服务器入口、Vite 插件、源映射、运行时启动时

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

---

配置参考

Sentry.init() 的关键选项

选项	类型	默认值	备注
dsn	string	—	必填；为空时 SDK 会被禁用
dataCollection	object	未设置时采用保守默认值	精细控制自动收集的类别（userInfo、cookies、httpHeaders、httpBodies、queryParams、genAI）。省略此项时，SDK 会回退到 sendDefaultPii（默认值为 false）。传入此对象（即使是 {}）也会将未设置类别切换为宽松默认值；可按类别选择退出。
integrations	Integration[]	SDK 默认值	按需包含 TanStack Router 跟踪、回放和反馈
enableLogs	boolean	false	启用 Sentry.logger.* API
tracesSampleRate	number	—	开发环境中为 1.0，生产环境中设为较低值
replaysSessionSampleRate	number	—	录制的所有会话所占比例
replaysOnErrorSampleRate	number	—	录制的错误会话所占比例
tunnel	string	—	可选的广告拦截器绕过端点
debug	boolean	false	SDK 诊断日志

TanStack Start 专用 API

API	用途
tanstackRouterBrowserTracingIntegration(router)	浏览器导航跟踪
wrapFetchWithSentry(...)	在 fetch 处理程序上进行服务器请求跟踪和错误捕获
sentryGlobalRequestMiddleware	捕获请求级服务器错误
sentryGlobalFunctionMiddleware	捕获服务器函数错误
sentryTanstackStart({...})	用于源映射和中间件插桩的 Vite 插件

---

验证

触发测试事件，以确认 Sentry 收到数据。

问题测试（前端）

<button
  type="button"
  onClick={() => {
    throw new Error("Sentry Test Error");
  }}
>
  Break the world
</button>

跟踪测试（前端 + API 路由）

<button
  type="button"
  onClick={async () => {
    await Sentry.startSpan({ name: "Example Frontend Span", op: "test" }, async () => {
      const res = await fetch("/api/sentry-example");
      if (!res.ok) {
        throw new Error("Sentry Example Frontend Error");
      }
    });
  }}
>
  Break the world
</button>

日志测试

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 阶段：交叉链接

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

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

如果存在未配置 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 后端服务	sentry-node-sdk

---

故障排除

问题	解决方案
未显示事件	设置 debug: true，验证 DSN，并确保客户端和服务端初始化文件都已运行
没有服务端跟踪	确认 src/server.ts 使用了 wrapFetchWithSentry，且运行时加载了 instrument.server.mjs
路由处理程序中的服务端错误缺失	确保 sentryGlobalRequestMiddleware 和 sentryGlobalFunctionMiddleware 位于数组首位
Source map 无法解析	验证 sentryTanstackStart 配置中的 SENTRY_AUTH_TOKEN、org 和 project
Vite 配置中 SENTRY_AUTH_TOKEN 未定义	使用 loadEnv(mode, process.cwd(), "") 或 .env.sentry-build-plugin
Replay 未录制	确保 integrations 中包含 replayIntegration()，且采样率不为零
反馈小组件不可见	确认已配置 feedbackIntegration()，并检查 CSS z-index 冲突
Sentry 中缺少日志	设置 enableLogs: true 并使用 Sentry.logger.* API
直接导入设置遗漏库的跟踪信息	尽可能优先使用 --import 启动方式；直接导入仅支持原生 Node 插桩
SSR 渲染异常未自动捕获	在错误边界／回退处理程序中使用 Sentry.captureException 手动捕获