sentry-nextjs-sdk

Sentry Next.js SDK

一个带有明确主张的向导，会扫描你的 Next.js 项目，并引导你完成跨全部三个运行时的完整 Sentry 设置：浏览器、Node.js 服务端和 Edge。

何时调用此 Skill

• 用户要求在 Next.js 应用中 "add Sentry to Next.js" 或 "set up Sentry"
• 用户想要安装或配置 @sentry/nextjs
• 用户想要为 Next.js 提供错误监控、链路追踪、会话回放、日志记录或性能分析
• 用户询问 instrumentation.ts、withSentryConfig() 或 global-error.tsx
• 用户想要捕获 server actions、server component 错误或 edge runtime 错误

注意： 下方的 SDK 版本和 API 反映撰写时 Sentry 文档的当前状态（@sentry/nextjs ≥8.28.0）。 实施前请务必对照 docs.sentry.io/platforms/javascript/guides/nextjs/ 进行核实。

---

阶段 1：检测

在给出任何建议之前，运行这些命令来了解项目：

# Detect Next.js version and existing Sentry
cat package.json | grep -E '"next"|"@sentry/'

# Detect router type (App Router vs Pages Router)
ls src/app app src/pages pages 2>/dev/null

# Check for existing Sentry config files
ls instrumentation.ts instrumentation-client.ts sentry.server.config.ts sentry.edge.config.ts 2>/dev/null
ls src/instrumentation.ts src/instrumentation-client.ts 2>/dev/null

# Check next.config
ls next.config.ts next.config.js next.config.mjs 2>/dev/null

# Check for existing error boundaries
find . -name "global-error.tsx" -o -name "_error.tsx" 2>/dev/null | grep -v node_modules

# Check build tool
cat package.json | grep -E '"turbopack"|"webpack"'

# Check for logging libraries
cat package.json | grep -E '"pino"|"winston"|"bunyan"'

# Check for companion backend
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

需要确定的内容：

问题	影响
Next.js 版本？	需要 13+；Turbopack 支持需要 15+
App Router 还是 Pages Router？	决定需要哪些错误边界文件（global-error.tsx 还是 _error.tsx）
@sentry/nextjs 已存在？	跳过安装，进入功能配置
已有 instrumentation.ts？	将 Sentry 合并进去，而不是替换它
是否使用 Turbopack？	withSentryConfig 中的 tree-shaking 仅适用于 webpack
检测到日志库？	建议集成 Sentry Logs
发现后端目录？	触发阶段 4 的交叉链接建议

---

阶段 2：推荐

根据你的发现给出具体建议。不要问开放式问题——先给出提案：

推荐（核心覆盖）：

• ✅ 错误监控 —— 始终启用；捕获服务端错误、客户端错误、server actions 和未处理的 promise 拒绝
• ✅ 链路追踪 —— 服务端请求追踪 + 跨所有运行时的客户端导航 span
• ✅ 会话回放 —— 推荐用于面向用户的应用；记录错误发生前后的会话

可选（增强可观测性）：

• ⚡ 日志记录 —— 通过 Sentry.logger.* 记录结构化日志；在需要 pino/winston 或日志搜索时推荐
• ⚡ 性能分析 —— 持续性能分析；需要 Document-Policy: js-profiling 响应头
• ⚡ AI 监控 —— OpenAI、Vercel AI SDK、Anthropic；在检测到 AI/LLM 调用时推荐
• ⚡ Crons —— 检测错过/失败的定时任务；在检测到 cron 模式时推荐
• ⚡ 指标 —— 通过 Sentry.metrics.* 自定义指标；在需要自定义 KPI 或业务指标时推荐

推荐逻辑：

功能	推荐时机...
错误监控	始终 —— 不可协商的基线
链路追踪	对 Next.js 始终推荐 —— 服务端路由追踪 + 客户端导航价值很高
会话回放	面向用户的应用、登录流程或结账页面
日志记录	应用使用结构化日志，或需要日志到追踪的关联
性能分析	性能关键型应用；客户端设置 Document-Policy: js-profiling
AI 监控	应用调用 OpenAI、Vercel AI SDK 或 Anthropic
Crons	应用有 Vercel Cron 任务、定时 API 路由或使用 node-cron
指标	应用需要通过 Sentry.metrics.* 自定义计数器、仪表或直方图

提出："我建议设置错误监控 + 链路追踪 + 会话回放。要我也添加日志记录或性能分析吗？"

---

阶段 3：引导

选项 1：向导（推荐）

npx @sentry/wizard@latest -i nextjs

向导会以交互方式引导你完成登录、组织/项目选择以及认证令牌设置——无需手动创建令牌。随后它会安装 SDK，创建所有必要的配置文件（instrumentation-client.ts、sentry.server.config.ts、sentry.edge.config.ts、instrumentation.ts），用 withSentryConfig() 包装 next.config.ts，配置 source map 上传，并添加一个 /sentry-example-page 用于验证。

运行向导后，跳转至验证。

---

选项 2：手动设置

安装

npm install @sentry/nextjs --save

创建 instrumentation-client.ts —— 浏览器 / 客户端运行时

较早的文档使用 sentry.client.config.ts —— 当前模式是 instrumentation-client.ts。

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN ?? "___PUBLIC_DSN___",

  sendDefaultPii: true,

  // 100% in dev, 10% in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Session Replay: 10% of all sessions, 100% of sessions with errors
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,

  integrations: [
    Sentry.replayIntegration(),
    // Optional: user feedback widget
    // Sentry.feedbackIntegration({ colorScheme: "system" }),
  ],
});

// Hook into App Router navigation transitions (App Router only)
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

创建 sentry.server.config.ts —— Node.js 服务端运行时

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Attach local variable values to stack frames
  includeLocalVariables: true,

  enableLogs: true,
});

创建 sentry.edge.config.ts —— Edge 运行时

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  enableLogs: true,
});

创建 instrumentation.ts —— 服务端注册钩子

对于 Next.js < 14.0.4，需要在 next.config 中设置 experimental.instrumentationHook: true。在 14.0.4+ 中已稳定。

import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }

  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// Automatically captures all unhandled server-side request errors
// Requires @sentry/nextjs >= 8.28.0
export const onRequestError = Sentry.captureRequestError;

运行时分发：

NEXT_RUNTIME	加载的配置文件
"nodejs"	sentry.server.config.ts
"edge"	sentry.edge.config.ts
（客户端 bundle）	instrumentation-client.ts（Next.js 直接处理）

App Router：创建 app/global-error.tsx

它会捕获根布局中的错误以及 React 渲染错误：

"use client";

import * as Sentry from "@sentry/nextjs";
import NextError from "next/error";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <NextError statusCode={0} />
      </body>
    </html>
  );
}

Pages Router：更新 pages/_error.tsx

import * as Sentry from "@sentry/nextjs";
import type { NextPageContext } from "next";
import NextErrorComponent from "next/error";

type ErrorProps = { statusCode: number };

export default function CustomError({ statusCode }: ErrorProps) {
  return <NextErrorComponent statusCode={statusCode} />;
}

CustomError.getInitialProps = async (ctx: NextPageContext) => {
  await Sentry.captureUnderscoreErrorException(ctx);
  return NextErrorComponent.getInitialProps(ctx);
};

用 withSentryConfig() 包装 next.config.ts

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  // your existing Next.js config
};

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Source map upload auth token (see Source Maps section below)
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Upload wider set of client source files for better stack trace resolution
  widenClientFileUpload: true,

  // Create a proxy API route to bypass ad-blockers
  tunnelRoute: "/monitoring",

  // Suppress non-CI output
  silent: !process.env.CI,
});

从中间件中排除隧道路由

如果你有 middleware.ts，请从认证或重定向逻辑中排除隧道路径：

// middleware.ts
export const config = {
  matcher: [
    // Exclude monitoring route, Next.js internals, and static files
    "/((?!monitoring|_next/static|_next/image|favicon.ico).*)",
  ],
};

---

Source Maps 设置

Source maps 使生产环境的堆栈跟踪可读——没有它们，你看到的只是压缩后的代码。这对生产应用来说是不可或缺的。

步骤 1：生成 Sentry 认证令牌

前往 sentry.io/settings/auth-tokens/ 并创建一个具有 project:releases 和 org:read 权限范围的令牌。

步骤 2：设置环境变量

# .env.sentry-build-plugin  (gitignore this file)
SENTRY_AUTH_TOKEN=sntrys_eyJ...

或在 CI secrets 中设置：

SENTRY_AUTH_TOKEN=sntrys_eyJ...
SENTRY_ORG=my-org        # optional if set in next.config
SENTRY_PROJECT=my-project # optional if set in next.config

步骤 3：添加到 .gitignore

.env.sentry-build-plugin

步骤 4：验证 authToken 已在 next.config.ts 中配置

withSentryConfig(nextConfig, {
  org: "my-org",
  project: "my-project",
  authToken: process.env.SENTRY_AUTH_TOKEN, // reads from .env.sentry-build-plugin or CI env
  widenClientFileUpload: true,
});

Source maps 会在每次 next build 时自动上传。

---

对于每个约定的功能

加载相应的参考文件并按照其步骤操作：

功能	参考文件	加载时机...
错误监控	references/error-monitoring.md	始终（基线）—— App Router 错误边界、Pages Router _error.tsx、服务端 action 包装
追踪	references/tracing.md	服务端请求追踪、客户端导航、分布式追踪、tracePropagationTargets
会话重放	references/session-replay.md	面向用户的应用；隐私掩码、canvas 录制、网络捕获
日志记录	references/logging.md	结构化日志、Sentry.logger.*、日志到追踪的关联
性能分析	references/profiling.md	持续性能分析、Document-Policy 头、nodeProfilingIntegration
AI 监控	references/ai-monitoring.md	应用使用 OpenAI、Vercel AI SDK 或 Anthropic
定时任务	references/crons.md	Vercel Cron、定时 API 路由、node-cron

对于每个功能：阅读参考文件，严格按照其步骤操作，并在继续之前进行验证。

---

验证

在完成向导或手动设置后，验证 Sentry 是否正常工作：

// Add temporarily to a server action or API route, then remove
import * as Sentry from "@sentry/nextjs";

throw new Error("Sentry test error — delete me");
// or
Sentry.captureException(new Error("Sentry test error — delete me"));

然后查看你的 Sentry Issues 仪表盘——错误应在约 30 秒内出现。

验证清单：

检查项	方法
客户端错误已捕获	在客户端组件中抛出错误，在 Sentry 中验证
服务端错误已捕获	在服务端操作或 API 路由中抛出错误
Edge 错误已捕获	在中间件或 edge 路由处理器中抛出错误
Source map 正常工作	检查堆栈跟踪是否显示可读的文件名
Session Replay 正常工作	检查 Sentry 仪表盘中的 Replays 标签页

---

配置参考

Sentry.init() 选项

选项	类型	默认值	说明
dsn	string	—	必填。客户端使用 NEXT_PUBLIC_SENTRY_DSN，服务端使用 SENTRY_DSN
tracesSampleRate	number	—	0–1；建议开发环境使用 1.0，生产环境使用 0.1
replaysSessionSampleRate	number	0.1	记录的所有会话的比例
replaysOnErrorSampleRate	number	1.0	记录的错误会话的比例
sendDefaultPii	boolean	false	在事件中包含 IP、请求头
includeLocalVariables	boolean	false	将局部变量值附加到堆栈帧（仅服务端）
enableLogs	boolean	false	启用 Sentry Logs 产品
environment	string	自动	"production"、"staging" 等
release	string	自动	设置为提交 SHA 或版本标签
debug	boolean	false	将 SDK 活动记录到控制台

withSentryConfig() 选项

选项	类型	说明
org	string	Sentry 组织 slug
project	string	Sentry 项目 slug
authToken	string	Source map 上传令牌（SENTRY_AUTH_TOKEN）
widenClientFileUpload	boolean	上传更多客户端文件以获得更好的堆栈跟踪
tunnelRoute	string	用于绕过广告拦截器的 API 路由路径（例如 "/monitoring"）
silent	boolean	抑制构建输出（建议使用 !process.env.CI）
webpack.treeshake.*	object	对 SDK 功能进行 tree-shake（仅 webpack，不适用于 Turbopack）

环境变量

变量	运行时	用途
NEXT_PUBLIC_SENTRY_DSN	客户端	浏览器 Sentry 初始化的 DSN（公开）
SENTRY_DSN	服务端 / Edge	服务端/edge Sentry 初始化的 DSN
SENTRY_AUTH_TOKEN	构建	Source map 上传认证令牌（机密）
SENTRY_ORG	构建	组织 slug（替代配置中的 org）
SENTRY_PROJECT	构建	项目 slug（替代配置中的 project）
SENTRY_RELEASE	服务端	发布版本字符串（从 git 自动检测）
NEXT_RUNTIME	服务端 / Edge	"nodejs" 或 "edge"（由 Next.js 内部设置）

---

第 4 阶段：交叉链接

完成 Next.js 设置后，检查是否有配套服务：

# Check for backend services in adjacent directories
ls ../backend ../server ../api ../services 2>/dev/null

# Check for backend language indicators
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml ../build.gradle 2>/dev/null | head -3

如果发现后端，建议匹配的 SDK 技能：

检测到的后端	建议技能
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
Java/Kotlin（pom.xml、build.gradle）	参见 docs.sentry.io/platforms/java/
Node.js（Express、Fastify、Hapi）	@sentry/node — 参见 docs.sentry.io/platforms/javascript/guides/express/

使用相同的 DSN 或关联项目连接前端和后端可实现 分布式追踪——在单个追踪视图中跨越浏览器、Next.js 服务端和后端 API 的堆栈跟踪。

---

故障排查

问题	原因	解决方案
未显示事件	DSN 配置错误，或 debug: false 隐藏了错误	暂时设置 debug: true；检查浏览器网络面板中是否有发往 sentry.io 的请求
堆栈跟踪显示的是压缩后的代码	未上传源映射	检查是否已设置 SENTRY_AUTH_TOKEN；运行 next build，并在构建输出中查找“Source Maps”
onRequestError 未触发	SDK 版本低于 8.28.0	升级：npm install @sentry/nextjs@latest
缺少 Edge 运行时错误	未加载 sentry.edge.config.ts	确认 instrumentation.ts 在 NEXT_RUNTIME === "edge" 时导入该文件
隧道路由返回 404	已设置 tunnelRoute，但缺少 Next.js 路由	插件会自动创建该路由；检查是否在添加 tunnelRoute 后运行了 next build
withSentryConfig 的摇树优化导致构建失败	正在使用 Turbopack	摇树优化选项仅适用于 webpack；使用 Turbopack 时，请移除 webpack.treeshake 选项
global-error.tsx 未捕获错误	缺少 "use client" 指令	将 "use client" 添加到 global-error.tsx 的第一行
Session Replay 未录制	客户端初始化中缺少 replayIntegration()	将 Sentry.replayIntegration() 添加到 instrumentation-client.ts 中的 integrations