feat(monitoring): 接入 Sentry 错误监控（免费 Developer tier） (#296)

Author: longsizhuo

.env.sample

@@ -29,6 +29,16 @@ INTERN_KEY=
 # 智谱 AI 开放平台 API Key，聊天与建议接口的默认免费模型 GLM-4.6V-Flash
 # 在 https://open.bigmodel.cn/ 注册后获取
 ZHIPU_API_KEY=
+
+# Sentry 错误监控（Developer plan 免费 5K errors / 10K perf units / 月）
+# NEXT_PUBLIC_SENTRY_DSN 是浏览器端需要的公开 DSN，暴露在前端 bundle 里属于设计，
+# SENTRY_AUTH_TOKEN 仅用于 next build 时上传 source map，私密。
+# SDK 只在 NODE_ENV=production 启用，本地 dev/preview 不会产生事件、不耗配额。
+# Vercel 端由 Sentry 集成自动注入；本地 dev 可不填。
+NEXT_PUBLIC_SENTRY_DSN=
+SENTRY_AUTH_TOKEN=
+SENTRY_ORG=involutionhell
+SENTRY_PROJECT=sentry-bole-notebook
 # Neon 项目 ID
 NEON_PROJECT_ID=
 # Neon 提供的 Postgres 连接。

instrumentation.ts

@@ -0,0 +1,18 @@
+/**
+ * Next.js 15+ 约定的启动 hook：每个 runtime 启动时各自拉对应 Sentry 配置，
+ * 避免在 edge runtime 错误加载 Node-only 代码。
+ *
+ * onRequestError 暴露给 Next.js 捕获服务端组件/路由层面的未捕获错误。
+ */
+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;

next.config.mjs

@@ -1,6 +1,7 @@
 // next.config.mjs
 import { createMDX } from "fumadocs-mdx/next";
 import createNextIntlPlugin from "next-intl/plugin";
+import { withSentryConfig } from "@sentry/nextjs";
 
 /**
  * IMPORTANT: remarkImage 配置已移至 source.config.ts 统一管理
@@ -150,4 +151,26 @@ const config = {
   },
 };
 
-export default withNextIntl(withMDX(config));
+const finalConfig = withNextIntl(withMDX(config));
+
+// Sentry 包裹：webpack 插件需要看到最终的 Next 配置才能上传 source map。
+// silent: !CI 让本地构建不刷日志，只在 Vercel CI 构建时打印。
+// widenClientFileUpload 扩大 source map 扫描范围，保证前端错误堆栈能解出来。
+// disableLogger 树摇掉 Sentry 自带 logger，减小 bundle 体积。
+//
+// 守门条件：只有在存在 SENTRY_AUTH_TOKEN 时才启用 withSentryConfig。
+// 贡献者 clone 仓库后没配 Sentry env 也能直接 `pnpm build` / `pnpm dev`，
+// 不会因为 webpack 插件缺凭据而构建失败。生产 Vercel 那边 env 齐全，正常上报。
+const enableSentry = Boolean(process.env.SENTRY_AUTH_TOKEN);
+
+export default enableSentry
+  ? withSentryConfig(finalConfig, {
+      org: process.env.SENTRY_ORG || "involutionhell",
+      project: process.env.SENTRY_PROJECT || "sentry-bole-notebook",
+      silent: !process.env.CI,
+      widenClientFileUpload: true,
+      disableLogger: true,
+      // 不启用 tunnelRoute：需要加 /monitoring rewrite，和现有 rewrites 交互
+      // 复杂；广告屏蔽对 docs 站影响小，后续真需要再打开。
+    })
+  : finalConfig;

package.json

@@ -45,6 +45,7 @@
     "@radix-ui/react-radio-group": "^1.3.8",
     "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@sentry/nextjs": "^10.49.0",
     "@types/mdx": "^2.0.13",
     "@types/pg": "^8.16.0",
     "@vercel/speed-insights": "^1.2.0",

pnpm-lock.yaml

@@ -0,0 +1,20 @@
+/**
+ * Sentry 浏览器端初始化。
+ *
+ * 免费 tier 策略（Developer plan，5K errors/月 + 10K perf units/月）：
+ * - 只在 production 启用，避免本地 dev/preview 污染配额
+ * - tracesSampleRate 0.1：10% 的页面 transaction 采样足够看性能趋势
+ * - 关闭 Session Replay：它是另外的独立配额（小），开了容易炸
+ * - 不启用 profiling（需要付费）
+ */
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  enabled: process.env.NODE_ENV === "production",
+  tracesSampleRate: 0.1,
+  replaysSessionSampleRate: 0,
+  replaysOnErrorSampleRate: 0,
+  // 线上开 false 省日志；排障时临时改 true
+  debug: false,
+});

sentry.client.config.ts

@@ -0,0 +1,12 @@
+/**
+ * Sentry Edge runtime 初始化（Middleware / Edge routes）。
+ * 当前项目未使用 edge runtime，保留配置以便未来迁移时无需补齐。
+ */
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  enabled: process.env.NODE_ENV === "production",
+  tracesSampleRate: 0.1,
+  debug: false,
+});

sentry.edge.config.ts

@@ -0,0 +1,12 @@
+/**
+ * Sentry Node.js runtime 初始化（Next.js API routes / Server Components / RSC）。
+ * 与 client 同策略：仅 production 启用，traces 10%，无 replay/profiling。
+ */
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  enabled: process.env.NODE_ENV === "production",
+  tracesSampleRate: 0.1,
+  debug: false,
+});