错误追踪与日志

生产环境出错是常态，关键是能快速发现和修复。错误追踪工具能帮你做到这一点。

为什么需要错误追踪

主动发现问题：用户报告前就知道出错了
快速定位：知道哪行代码出错
了解影响范围：多少用户受影响
追踪修复效果：确认问题是否解决

快速开始：Sentry

1. 注册账号

访问 sentry.io，用 GitHub 登录。

2. 创建项目

选择框架（如 Next.js、React、Node.js）。

3. 安装 SDK

npm install @sentry/nextjs
# 或
npm install @sentry/react
# 或
npm install @sentry/node

4. 配置

Next.js

npx @sentry/wizard@latest -i nextjs

自动生成配置文件：

// sentry.client.config.js
import * as Sentry from "@sentry/nextjs"

Sentry.init({
  dsn: "your-dsn-here",
  tracesSampleRate: 1.0,
})

React

// src/index.js
import * as Sentry from "@sentry/react"

Sentry.init({
  dsn: "your-dsn-here",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
})

Node.js

// server.js
const Sentry = require("@sentry/node")

Sentry.init({
  dsn: "your-dsn-here",
  tracesSampleRate: 1.0,
})

// 错误处理中间件
app.use(Sentry.Handlers.errorHandler())

5. 测试

// 手动触发错误
throw new Error("Test Sentry")

在 Sentry 后台应该能看到错误。

配置环境变量

不要把 DSN 硬编码，使用环境变量：

# .env.local
NEXT_PUBLIC_SENTRY_DSN=your-dsn-here

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
})

源码映射（Source Maps）

生产环境代码通常是压缩的，源码映射能还原到原始代码。

Next.js

在 next.config.js 中：

module.exports = {
  productionBrowserSourceMaps: true,
}

上传到 Sentry

# 安装 CLI
npm install @sentry/cli

# 上传 source maps
npx sentry-cli sourcemaps upload --org your-org --project your-project ./out

或在构建时自动上传（Next.js）：

// next.config.js
const { withSentryConfig } = require("@sentry/nextjs")

module.exports = withSentryConfig(
  {
    // Next.js 配置
  },
  {
    // Sentry 配置
    silent: true,
    org: "your-org",
    project: "your-project",
  }
)

自定义错误信息

添加上下文

Sentry.setContext("user", {
  id: user.id,
  email: user.email,
})

Sentry.setTag("page", "checkout")

手动捕获错误

try {
  // 可能出错的代码
} catch (error) {
  Sentry.captureException(error, {
    tags: {
      section: "payment",
    },
    extra: {
      orderId: order.id,
    },
  })
}

添加面包屑

Sentry.addBreadcrumb({
  category: "auth",
  message: "User logged in",
  level: "info",
})

通知设置

邮件通知

在 Sentry 后台：

Settings → Alerts
创建规则
选择触发条件（如新错误、错误频率）
选择通知方式（邮件、Slack、Discord）

Slack 集成

Settings → Integrations
搜索 Slack
授权连接
选择频道

查看错误

错误详情

Sentry 提供：

错误堆栈
用户信息
浏览器/设备信息
面包屑（用户操作路径）
源码位置

错误分组

相同的错误自动分组，可以看到：

影响用户数
发生次数
首次/最后发生时间

标记错误

Resolve：已修复
Ignore：忽略
Assign：分配给团队成员

性能监控

Sentry 也支持性能监控：

Sentry.init({
  dsn: "your-dsn-here",
  tracesSampleRate: 0.1, // 采样 10% 的请求
})

可以看到：

页面加载时间
API 请求时间
数据库查询时间

免费额度

Sentry 免费计划：

5000 错误/月
10000 性能事件/月
1 个项目
保留 30 天

对于 MVP 完全够用。

常见问题

错误太多怎么办

设置采样率（不是所有错误都上报）
过滤已知错误
升级付费计划

如何过滤错误

Sentry.init({
  dsn: "your-dsn-here",
  beforeSend(event, hint) {
    // 过滤特定错误
    if (event.exception?.values?.[0]?.value?.includes("Network Error")) {
      return null
    }
    return event
  },
})

本地开发时不想上报

Sentry.init({
  dsn: process.env.NODE_ENV === "production" ? "your-dsn-here" : "",
})

其他日志方案

简单方案：Console + 托管平台日志

console.error("Error:", error)

在 Vercel/Railway 等平台查看日志。

优点：零配置缺点：不能聚合、搜索困难

自建方案：Winston + Loki

适合有特殊需求的场景，但配置复杂。

错误追踪与日志

目录