Next.js App Router 中的 Sentry:服务器和客户端错误、没有 PII 的源映射
应该发生什么
服务器组件、路由处理程序、服务器操作或浏览器中的错误将通过可读堆栈(文件名和源代码行,而不是缩小的包)发送到 Sentry,并带有发布指示,并且事件中没有个人用户数据。
安装
npx @sentry/wizard@latest -i nextjs
该向导创建文件并编辑 next.config。弄清楚他做了什么,然后你支持他们:
instrumentation-client.ts(在旧版本的 SDK 中 -sentry.client.config.ts) - 在浏览器中初始化。sentry.server.config.ts和sentry.edge.config.ts- 用于 Node.js 和 Edge 运行时。instrumentation.ts是服务器启动时 Next.js 调用的入口点。app/global-error.tsx— 根布局的错误限制。
// instrumentation.ts
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");
}
export const onRequestError = Sentry.captureRequestError;onRequestError 是一个 Next.js 15 挂钩,在路由处理程序和服务器操作中出现渲染错误时调用。如果没有这一行,服务器错误通常不会到达 Sentry:Next.js 会自行拦截它们并向用户显示错误页面。
没有 PII 的服务器配置
// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.APP_ENV ?? "production",
release: process.env.SENTRY_RELEASE,
sendDefaultPii: false,
tracesSampleRate: 0.1,
beforeSend(event) {
if (event.request) {
delete event.request.cookies;
delete event.request.data;
if (event.request.headers) {
delete event.request.headers.authorization;
delete event.request.headers.cookie;
}
}
return event;
},
});sendDefaultPii: false(这是默认值,但明确更好) - SDK 不附加 IP 地址、cookie 和用户数据标头。beforeSend- 最后一行:删除可以通过集成或您自己的上下文获得的内容。请求正文 (request.data) 特别危险:它包含登录表单中的密码和付款数据。- 仅通过标识符指定用户:
Sentry.setUser({ id: user.id })。错误事件中的电子邮件和姓名不是调试所需要的,而是由第三方存储的。 tracesSampleRate: 0.1- 10% 的性能跟踪请求。生产中的值为 1.0 将很快耗尽配额。
另请检查错误文本。 `throw new Error(用户 ${email} 未找到) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii`不会阻止它。
客户端和会话重播
// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: 0.1,
replaysSessionSampleRate: 0,
replaysOnErrorSampleRate: 0.2,
integrations: [Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })],
});Replay 写入页面的 DOM。 maskAllText 和 blockAllMedia 默认启用 - 在确保页面不包含个人信息的情况下请勿禁用它们。仅记录失败的会话 (replaysOnErrorSampleRate) 为调试提供上下文,而无需持续监视用户。
浏览器中的 DSN 本质上是公开的:它只允许您发送事件。在Sentry项目设置中限制允许的域(Allowed Domains),这样其他人的站点就不会阻塞您的项目。
源映射
// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";
const nextConfig = { /* ... */ };
export default withSentryConfig(nextConfig, {
org: "my-org",
project: "web",
authToken: process.env.SENTRY_AUTH_TOKEN,
silent: !process.env.CI,
widenClientFileUpload: true,
sourcemaps: { deleteSourcemapsAfterUpload: true },
});在 next build 期间,插件将源映射加载到 Sentry 中。 deleteSourcemapsAfterUpload 会在上传后从构建中删除 .map 文件,这样源代码就不会与您网站上的每个人共享。部署后检查:从 /_next/static/chunks/ 向任何 .js.map 发出的请求应返回 404。
SENTRY_AUTH_TOKEN 是具有项目写入权限的机密。仅在构建阶段的 CI 中需要它,而不是在运行时以及带有 NEXT_PUBLIC_ 前缀的变量中。
诊断
- 堆栈已缩小。 源映射未加载或事件发布与下载发布不一致。
sentry-cli sourcemaps explain <event_id>命令解释了为什么特定事件没有被符号化。 - 不会出现服务器错误。
instrumentation.ts中没有onRequestError,或者该文件不在项目根目录中(如果有src/- 在src/内)。 - 某些用户不会出现浏览器错误。 广告拦截器会削减对 Sentry 的请求。
withSentryConfig中的tunnelRoute: "/monitoring"选项将通过您的域代理事件。如果站点有严格的 CSP,请将接收域添加到connect-src。 - 什么也没有到达。 暂时启用
Sentry.init中的debug: true并查看服务器日志和浏览器控制台。
噪音和配额
并非每一个错误都值得大惊小怪。过滤掉预期的:取消的请求、浏览器扩展错误、来自机器人的 404。对于已知消息使用 ignoreErrors,对于扩展脚本使用 denyUrls。每天都会出现一千个相同的不重要错误的项目教会团队根本不要看 Sentry。
当Sentry冗余时
对于小型内部服务,具有 error 级别的结构化日志及其编号警报可能就足够了。当存在客户端 JavaScript、大量用户并且您需要对错误进行分组并查看是哪个版本带来了这些错误时,Sentry 就会得到回报。