配置 Sentry 错误追踪

• Sentry 账号 — 前往 sentry.io 注册 ↗。免费套餐每月包含 5K 事件 + 10K 回放，对于个人项目或小型 SaaS 完全够用。
• 应用运行环境 — Sentry 几乎为所有平台提供了 SDK，常用平台如下：
  • 浏览器 JavaScript ↗
  • Node.js / Express ↗
  • Next.js ↗
  • Python（Django / Flask / FastAPI）↗
  • Swift / iOS / macOS ↗
  • Android（Kotlin / Java）↗
  • React Native ↗

登录 sentry.io ↗，点击 Projects → Create Project，选择平台（如 "Node.js"、"Next.js"），填写名称，点击 Create Project。

Sentry 会显示 DSN，格式如下：

https://[email protected]/678901

复制后存入后端环境变量：

SENTRY_DSN=https://[email protected]/678901

DSN 不像 API 密钥那样需要严格保密——放在客户端 bundle 中也没问题——但请将其视为配置项统一管理。

npm install --save @sentry/node

其他运行时请使用对应的安装命令：npm install @sentry/react、pip install --upgrade sentry-sdk 等。具体请参考第 0 步中对应平台的文档页面。

请在应用执行任何其他操作之前初始化 Sentry。在 Node 中，这意味着要放在入口文件的最开头：

// Must be the FIRST import in your app's entry file
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,   // 100% perf monitoring while you're learning; lower later
  environment: process.env.NODE_ENV || "development",
});

// ... rest of your app

对于浏览器 JS、Next.js 或 Python，写法完全相同：在启动时调用一次 Sentry.init({ dsn: ..., ... })。各平台文档（第 0 步）会说明具体位置。

手动触发一个错误，确认 Sentry 已正常接入：

Sentry.captureException(new Error("Sentry test from my app"));

你也可以触发一个真实的未捕获错误——Sentry 会自动安装全局处理器，因此任何未捕获的异常或未处理的 Promise 拒绝都会自动上报，无需额外操作。

前往 sentry.io → Issues ↗，测试错误应在几秒内出现。点击查看堆栈跟踪、请求上下文和操作面包屑。

将应用版本号传给 Sentry，这样每条错误都会打上版本标签——你可以清楚地看到"这个 bug 是从 1.4.2 开始出现的"。

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: "myapp@" + process.env.APP_VERSION,  // e.g. [email protected]
  environment: process.env.NODE_ENV,
});

结合部署流水线中的 Sentry CLI ↗，可以创建版本记录：

sentry-cli releases new "myapp@$APP_VERSION"
sentry-cli releases finalize "myapp@$APP_VERSION"

生产环境的 JS 代码经过压缩混淆。没有 source map，Sentry 中的堆栈跟踪会显示为 a.b.c at e.min.js:1:1234，毫无参考价值。

官方向导会自动完成这一步：

# Next.js
npx @sentry/wizard@latest -i nextjs

# React (Vite)
npx @sentry/wizard@latest -i sourcemaps

也可以通过 sentry-cli sourcemaps ↗ 手动上传。原生 iOS/Android 平台：SDK 通过 Gradle/CocoaPods 插件自动处理 dSYM / mapping 文件。

错误开始上报后，你会看到一些噪音（Chrome 扩展报错、预期内的校验错误、开发模式 bug）。可以通过以下方式过滤：

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  beforeSend(event, hint) {
    // Skip dev errors
    if (process.env.NODE_ENV === "development") return null;
    // Skip known noise
    const err = hint.originalException;
    if (err && err.message && err.message.includes("ResizeObserver loop")) {
      return null;
    }
    return event;
  },
  ignoreErrors: [
    "ResizeObserver loop limit exceeded",
    /^Network request failed$/,
  ],
});

每条被忽略的规则都能节省事件配额、减少告警噪音。随着运行时间积累，持续优化这些规则。

项目的默认配置会在出现新问题时发送邮件通知。如需自定义：

进入 Sentry → 你的项目 → Alerts → Create Alert。常用规则：

• 峰值告警 — 当单个问题的事件数超过阈值时触发（如 1 小时内 100 次事件）。
• 新问题告警 — 当生产环境出现新的错误类型时触发。
• 回归告警 — 当已解决的问题在新版本中重新出现时触发。

通过告警集成将通知路由到 Slack、PagerDuty 或邮件。告警文档 ↗。

点击仪表盘中的任意问题，可以看到：

• 堆栈跟踪，包含代码上下文（不只是 file:line，还有前后几行代码）。
• 操作面包屑 — 错误发生前最近 N 次用户/系统事件（点击、网络请求、控制台日志）。
• 标签 — 环境、版本、操作系统、浏览器、用户 ID。
• 受影响用户数 — 独立用户计数（匿名或已识别）。
• Session Replay（如已启用）— 类似视频的回放，还原用户出错前的操作过程。Session Replay ↗。

免费套餐：每月 5,000 条错误 + 10,000 条性能事件 + 50 次回放。如果热路径中存在未捕获的错误，真实生产应用很快就会超出这一限制。

付费套餐 Team 版起价约 $26/月，一旦应用有了真实用户，这笔投入是值得的。Sentry 定价 ↗。

自托管选项：Sentry 是开源的，你可以自行部署 ↗，但运维成本不低（Docker Compose、ClickHouse、Postgres、Redis）。大多数人不会这么做。