SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sentry-nextjs-sdk

sentry-nextjs-sdk

部署与运维

查看项目

更新于 10-14 19:29

技能介绍

Sentry Next.js SDK 是一个面向 Next.js 项目的 Sentry 接入技能，定位为「有明确主张的向导」：它会先扫描你的 Next.js 项目，再引导你完成 Sentry 在三种运行时下的完整配置，即浏览器（客户端）、Node.js 服务端与 Edge 运行时。

一、适用场景 资料列出以下调用时机：用户要求「add Sentry to Next.js」或在 Next.js 应用中「set up Sentry」；需要安装或配置 @sentry/nextjs；需要为 Next.js 配置错误监控、追踪、会话回放、日志或性能分析（profiling）；询问 instrumentation.ts、withSentryConfig() 或 global-error.tsx；需要捕获 server actions、server component 错误或 edge runtime 错误。

二、工作流程 技能按阶段推进：

  1. 检测（Phase 1） 通过一组命令了解项目现状，包括：检测 Next.js 版本与是否已存在 Sentry；检测路由类型（App Router 还是 Pages Router）；检查已有 Sentry 配置文件（instrumentation.ts、instrumentation-client.ts、sentry.server.config.ts、sentry.edge.config.ts 等）；检查 next.config 文件；查找已有错误边界（global-error.tsx、_error.tsx）；检测构建工具（turbopack、webpack）；检测日志库（pino、winston、bunyan）；检查是否存在配套后端目录。资料说明这些检测项各自对应不同影响，例如 Next.js 版本 13+ 为基本要求、15+ 才支持 Turbopack；App Router 与 Pages Router 决定需要的错误边界文件（global-error.tsx 对比 _error.tsx）；已存在 instrumentation.ts 时应合并而非替换；检测到 Turbopack 意味着 withSentryConfig 的 tree-shaking 仅适用于 webpack。

  2. 推荐（Phase 2） 基于检测结果给出明确建议而非开放式提问。核心覆盖项包括：错误监控（始终启用）、追踪（Next.js 始终推荐）、会话回放（面向用户的应用程序推荐）。可选项包括：日志（使用结构化日志或需要日志与追踪关联时）、性能分析（性能关键应用，客户端需设置 Document-Policy: js-profiling 头）、AI 监控（调用 OpenAI、Vercel AI SDK 或 Anthropic 时）、Crons（存在 Vercel Cron、定时 API 路由或 node-cron 时）、Metrics（需要自定义计数器、仪表或直方图时）。资料给出的推荐示例是：建议设置 Error Monitoring + Tracing + Session Replay，并询问是否同时添加 Logging 或 Profiling。

  3. 引导（Phase 3） 提供两种方式。

方式一：向导（推荐） 运行 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 用于验证。运行向导后可直接跳到验证环节。

方式二：手动设置 使用 npm install @sentry/nextjs --save 安装。资料给出各运行时的配置文件示例，包括：

  • instrumentation-client.ts（浏览器/客户端运行时），资料特别指出旧文档使用 sentry.client.config.ts，而当前模式是 instrumentation-client.ts；其中包含 dsn、sendDefaultPii、tracesSampleRate（开发 1.0、生产 0.1）、会话回放采样率（会话 0.1、出错时 1.0）、enableLogs、replayIntegration() 等，并导出 onRouterTransitionStart = Sentry.captureRouterTransitionStart（仅 App Router）。
  • sentry.server.config.ts（Node.js 服务端运行时），包含 includeLocalVariables: true 等。
  • sentry.edge.config.ts（Edge 运行时）。
  • instrumentation.ts（服务端注册钩子），按 NEXT_RUNTIME 为 "nodejs" 或 "edge" 分别加载对应配置；资料说明 Next.js < 14.0.4 需要 experimental.instrumentationHook: true，14.0.4+ 已稳定；并导出 onRequestError = Sentry.captureRequestError（需 @sentry/nextjs >= 8.28.0）。

错误边界方面：App Router 需创建 app/global-error.tsx（需 "use client"，用于捕获根布局与 React 渲染错误）；Pages Router 需更新 pages/_error.tsx，使用 Sentry.captureUnderscoreErrorException(ctx)。

next.config.ts 需用 withSentryConfig() 包装，可选配置包括 org、project、authToken（读取 SENTRY_AUTH_TOKEN）、widenClientFileUpload、tunnelRoute（如 "/monitoring"，用于绕过广告拦截器）、silent（非 CI 时静默）。若项目有 middleware.ts，需将 tunnel 路径从鉴权或重定向逻辑中排除，资料给出了对应的 matcher 示例。

Source Maps 设置方面，资料将其描述为生产环境不可省略的一环，步骤包括：创建具备 project:releases 与 org:read 权限的 Sentry auth token；设置环境变量（.env.sentry-build-plugin 需加入 .gitignore，或在 CI secrets 中设置）；确认 next.config.ts 中 authToken 已接入。Source maps 会在每次 next build 时自动上传。

对于每个已同意的功能，技能会加载对应参考文件并按步骤执行：Error Monitoring（references/error-monitoring.md，始终加载）、Tracing（references/tracing.md）、Session Replay（references/session-replay.md）、Logging（references/logging.md）、Profiling（references/profiling.md）、AI Monitoring（references/ai-monitoring.md）、Crons（references/crons.md）。

  1. 验证 在 server action 或 API 路由中临时抛出错误或调用 Sentry.captureException，然后在 Sentry Issues 面板检查，错误应在约 30 秒内出现。验证清单涵盖：客户端错误、服务端错误、Edge 错误是否被捕获，Source Maps 是否生效（堆栈显示可读文件名），以及会话回放是否工作。

  2. 交叉链接（Phase 4） 完成 Next.js 设置后，检测相邻目录中的后端服务。若发现后端，则建议匹配的 SDK 技能：Go（go.mod）对应 sentry-go-sdk；Python（requirements.txt、pyproject.toml）对应 sentry-python-sdk；Ruby（Gemfile）对应 sentry-ruby-sdk；Java/Kotlin 参考官方 Java 平台文档；Node.js（Express、Fastify、Hapi）参考 @sentry/node 对应指南。资料指出，前后端使用同一 DSN 或关联项目可实现分布式追踪，使浏览器、Next.js 服务端与后端 API 的堆栈出现在同一条追踪视图中。

三、配置参考 资料列出了 Sentry.init() 的选项（dsn、tracesSampleRate、replaysSessionSampleRate、replaysOnErrorSampleRate、sendDefaultPii、includeLocalVariables、enableLogs、environment、release、debug）及其类型、默认值与说明；withSentryConfig() 的选项（org、project、authToken、widenClientFileUpload、tunnelRoute、silent、webpack.treeshake.*）；以及环境变量（NEXT_PUBLIC_SENTRY_DSN、SENTRY_DSN、SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT、SENTRY_RELEASE、NEXT_RUNTIME）对应的运行时与用途。

四、故障排查 资料提供了常见问题表，例如：事件不出现（DSN 配置错误或 debug 关闭，可临时设 debug: true 并检查网络请求）；堆栈显示压缩代码（Source Maps 未上传，检查 SENTRY_AUTH_TOKEN 与构建输出）；onRequestError 未触发（SDK 版本低于 8.28.0，需升级）；Edge 运行时错误缺失（sentry.edge.config.ts 未被加载，检查 instrumentation.ts）；tunnel 路由返回 404；withSentryConfig tree-shaking 导致构建失败（Turbopack 下应移除相关选项）；global-error.tsx 未捕获错误（缺少 "use client"）；会话回放未录制（客户端 init 缺少 replayIntegration()）。

五、限制与注意事项 资料强调：文中 SDK 版本与 API 反映撰写时的 Sentry 文档（@sentry/nextjs ≥8.28.0），实施前应始终对照 docs.sentry.io/platforms/javascript/guides/nextjs/ 验证。tree-shaking 仅适用于 webpack，不适用于 Turbopack。此外，关于收费、价格、具体效果等资料暂未提供。