参考：SDK 集成、Source Map 命令与易错点

基于 Sentry 8.x · 核于 2026-08

速查

• Sentry 定位：应用错误追踪平台，只管错误（异常事件），不做日志（归 ELK）/指标（归 Prometheus）。
• 核心概念：Event（单次错误）/ Issue（同源归并组，按 fingerprint）/ Release（版本）/ Project（应用隔离）。
• fingerprint 去重：默认按 stack trace 关键帧算指纹，栈相同归同一 issue——避免同源错误刷屏。
• Source Map：上传到 Sentry 还原压缩栈到源码行；不要部署到生产 CDN（泄露源码）。
• Release tracking：SDK 传 release + 上传 Source Map 带 release → 标记错误首次版本 + 检测回归。
• Performance：trace/span 模型，自动埋点慢请求，与错误关联；采样上报。
• Session Replay：DOM 录制回放现场，排查「无法复现」错误；默认遮罩敏感数据。

一、SDK 集成速查

前端（React）

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: "https://xxx@o123.ingest.sentry.io/456",
  release: "myapp@1.2.0",                  // Release tracking
  environment: "production",
  tracesSampleRate: 0.2,                   // 性能采样 20%
  replaysOnErrorSampleRate: 1.0,           // 报错会话 100% 录 Replay
  replaysSessionSampleRate: 0.1,           // 常规会话 10% 录
  integrations: [
    Sentry.browserTracingIntegration(),    // 自动埋点 fetch/XHR
    Sentry.replayIntegration({             // Session Replay
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
});

// ErrorBoundary（React 专用）
<Sentry.ErrorBoundary fallback={<p>出错了</p>}>
  <App />
</Sentry.ErrorBoundary>;

// 手动上报
Sentry.captureException(new Error("手动上报的错误"));
Sentry.captureMessage("提示信息", "warning");

前端（Vue）

import * as Sentry from "@sentry/vue";

Sentry.init({
  App,                                      // Vue 应用实例
  dsn: "...",
  release: "myapp@1.2.0",
  integrations: [
    Sentry.browserTracingIntegration({ router }),  // 自动埋点路由
  ],
  tracesSampleRate: 0.2,
});

后端（Python）

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
    dsn="https://xxx@sentry.io/123",
    release="myapi@1.2.0",
    environment="production",
    traces_sample_rate=0.2,
    integrations=[DjangoIntegration()],     # Django 自动 hook
)
# 上报：
try:
    risky_operation()
except Exception as e:
    sentry_sdk.capture_exception(e)

后端（Node.js）

const Sentry = require("@sentry/node");
Sentry.init({
  dsn: "...",
  release: "myapi@1.2.0",
  tracesSampleRate: 0.2,
});
// Express 集成（必须在所有中间件前 + 路由后）
app.use(Sentry.Handlers.requestHandler());
app.get("/api/...", ...);
app.use(Sentry.Handlers.errorHandler());   // 捕获未处理错误

二、Source Map 上传命令

sentry-cli

# 安装
npm i -g @sentry/cli

# 配置（CI 环境变量）
export SENTRY_AUTH_TOKEN=xxx              # 在 Sentry 设置生成
export SENTRY_ORG=my-org
export SENTRY_PROJECT=my-frontend

# 创建 release（与 SDK init 的 release 一致）
sentry-cli releases new myapp@1.2.0

# 上传 Source Map
sentry-cli sourcemaps upload \
  --release myapp@1.2.0 \
  --strip-common-prefix \                 # 去掉公共路径前缀
  dist/assets/

# 关联 commit（Release tracking）
sentry-cli releases set-commits myapp@1.2.0 --auto

# 标记部署
sentry-cli releases deploys myapp@1.2.0 new -e production

# finalize（发布完成）
sentry-cli releases finalize myapp@1.2.0

构建工具插件

// vite.config.ts（@sentry/vite-plugin）
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default {
  build: {
    sourcemap: "hidden",                  // 生成但不引用（不上 CDN）
  },
  plugins: [
    sentryVitePlugin({
      org: "my-org",
      project: "my-frontend",
      authToken: process.env.SENTRY_AUTH_TOKEN,
      release: { name: "myapp@1.2.0" },
      sourcemaps: { filesToDeleteAfterUpload: ["dist/assets/*.js.map"] },
    }),
  ],
};

三、issue 状态速查

状态	含义	触发
unresolved	待处理	默认（新错误）
assigned	已分配	手动指派
resolved	已修复	手动 / 上传新 release 自动
ignored	忽略	手动（已知问题不修）
regression	回归	resolved 后又出现（自动）

四、采样率配置速查

Sentry.init({
  tracesSampleRate: 0.2,           // Performance trace：20% 请求采（量大要采样）
  // 错误事件默认全采（错误稀有且重要，不采样）
  replaysSessionSampleRate: 0.1,   // Replay 常规会话：10%
  replaysOnErrorSampleRate: 1.0,   // Replay 报错会话：100%（报错必录）
});

• 错误全采：错误稀有且重要，不采样。但可设 beforeSend 过滤已知噪音（如第三方脚本错误）。
• 性能采样：trace 量大，必采样（20% 足够看趋势）。
• Replay 分级：报错会话必录（replaysOnErrorSampleRate: 1.0），常规会话低采样（省钱）。

五、自定义上下文与 tags

// 用户信息（关联到错误）
Sentry.setUser({ id: user.id, email: user.email, username: user.name });

// tags（可索引、可过滤，低基数）
Sentry.setTag("page", "checkout");
Sentry.setTag("user_role", "vip");

// extra（不可索引，仅展示，高基数可用）
Sentry.setExtra("cart_items", cart.items);

// breadcrumb（事件前发生的事，自动记录 fetch/click/console）
Sentry.addBreadcrumb({
  category: "ui",
  message: "点击了下单按钮",
  level: "info",
});

// 上下文分组（scope）
Sentry.withScope(scope => {
  scope.setTag("feature", "payment");
  scope.setExtra("order_id", orderId);
  Sentry.captureException(err);
});

六、易错点清单

• 「Sentry 做日志全文检索」：错。Sentry 只存异常事件，全文检索归 ELK/Loki。
• 「Sentry 做时序指标监控」：错。指标监控归 Prometheus，Sentry 的 Performance 是附赠。
• 「Source Map 部署到生产 CDN」：错。泄露源码——只上传 Sentry，构建产物不发 .map。
• 「错误事件要采样省成本」：错。错误稀有且重要，默认全采；性能 trace 才采样。
• 「fingerprint 去重不重要」：错。不去重同源错误刷屏，开发者会被淹没。
• 「Session Replay 在 self-hosted 完整支持」：错。Replay 主要在 SaaS，self-hosted 受限。
• 「Sentry 替代 APM」：错。Performance 是错误优先的附赠，深度不及专用 APM（拓扑/调用链聚合）。
• 「SDK 不需要埋点自动捕获」：部分对（自动 hook unhandled），但手动 captureException 和 ErrorBoundary 更可控。
• 「Release tracking 没必要」：错。无 release 无法标记首次出现版本、无法检测回归。
• 「前后端错误无法关联」：错。sentry-trace header 传播 trace_id，可在 Sentry 关联同一请求前后端链路。
• 「Replay 上传明文密码」：错。默认遮罩密码框，可配 maskAllText 进一步保护 PII。
• 「sentry-cli 上传 Source Map 不带 release」：错。必须带 release 与 SDK init 一致，否则无法关联还原。

权威链接

• Sentry 官方文档
• 前端 React SDK
• Source Map 上传
• Release tracking
• Session Replay
• Performance Monitoring
• sentry-cli
• 本站幻灯片：Sentry