Sentry 错误监控

约 1094 字大约 4 分钟

布欧-Lewyon

2026-05-15

首页 › React › Sentry 错误监控

Sentry 是目前最流行的开源错误监控平台，支持前后端。生产环境接入 Sentry，能第一时间发现线上 Bug 并定位到源码。

核心概念

概念	说明
Event	单次错误/异常，包含 stack trace、breadcrumbs、请求上下文
Breadcrumb	错误发生前的"面包屑"——用户操作、网络请求、console 日志
Transaction	一次完整请求/页面加载的性能追踪
Span	Transaction 中的单个操作（如 API 调用、组件渲染）
Source Map	上传后可还原混淆代码中的源码位置和行号

安装与初始化

npm install @sentry/react @sentry/vite-plugin

Vite 插件配置

// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  build: {
    sourcemap: true, // 必须开启，用于上传 Source Map
  },
  plugins: [
    sentryVitePlugin({
      org: 'your-org',
      project: 'your-project',
      authToken: process.env.SENTRY_AUTH_TOKEN, // 从 Sentry Settings → API 获取
      telemetry: false,
    }),
  ],
});

在应用入口初始化

// main.ts
import * as Sentry from '@sentry/react';
import { BrowserTracing } from '@sentry/tracing';

Sentry.init({
  dsn: 'https://your-dsn@sentry.io/123456',
  environment: import.meta.env.MODE,            // 'production' | 'development'
  release: `app@${__APP_VERSION__}`,

  // 采样率
  tracesSampleRate: import.meta.env.PROD ? 0.2 : 1.0, // 性能追踪采样
  replaysSessionSampleRate: 0.1,                // Session Replay 采样
  replaysOnErrorSampleRate: 1.0,                // 错误时必录

  integrations: [
    new BrowserTracing(),
    new Sentry.Replay(),                        // 录制用户操作回放
  ],

  // 忽略某些错误（如浏览器插件导致的）
  ignoreErrors: [
    'ResizeObserver loop limit exceeded',
    'NetworkError when attempting to fetch resource.',
    'top.GLOBALS',
  ],
});

捕获错误

自动捕获

初始化后，Sentry 会自动捕获：

未捕获的 Promise rejection
window.onerror
React 渲染错误（配合 Sentry.ErrorBoundary）

React Error Boundary

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

function App() {
  return (
    <Sentry.ErrorBoundary
      fallback={({ error, resetError }) => (
        <div role="alert" style={{ padding: 40, textAlign: 'center' }}>
          <h2>应用发生错误</h2>
          <pre style={{ color: 'red' }}>{error.message}</pre>
          <button onClick={resetError}>重试</button>
          <button onClick={() => Sentry.showReportDialog()}>反馈问题</button>
        </div>
      )}
    >
      <MainApp />
    </Sentry.ErrorBoundary>
  );
}

手动上报

// 主动上报异常
try {
  await riskyOperation();
} catch (error) {
  Sentry.captureException(error, {
    tags: { feature: 'checkout', payment_method: 'alipay' },
    extra: { userId, orderId },
  });
}

// 上报自定义消息
Sentry.captureMessage('用户主动取消付款', {
  level: 'info',
  tags: { feature: 'checkout' },
});

// 设置当前用户（自动附加到后续所有 Event）
Sentry.setUser({ id: '123', email: 'user@example.com' });

// 设置标签（便于过滤）
Sentry.setTag('version', '2.3.1');
Sentry.setTags({ feature: 'dashboard', module: 'chart' });

性能追踪

自动追踪页面加载

BrowserTracing 自动为每个路由变化创建 Transaction：

new BrowserTracing({
  routingInstrumentation: Sentry.reactRouterV6Instrumentation(
    React.useEffect,
    useLocation,
    useNavigationType,
    createRoutesFromChildren,
    matchRoutes,
  ),
});

手动创建 Span

const transaction = Sentry.getActiveTransaction();
const span = transaction?.startChild({
  op: 'http',
  description: 'POST /api/order',
});

try {
  await fetch('/api/order', { method: 'POST', body: ... });
} finally {
  span?.finish(); // 记录耗时
}

Source Map 与源码定位

生产环境代码通常已混淆压缩，Sentry 需要 Source Map 才能还原。

自动上传（Vite Plugin）

如上文的 sentryVitePlugin，在构建时自动将 Source Map 推送到 Sentry。

手动上传（ci 脚本）

# 使用 sentry-cli
sentry-cli releases files app@1.0.0 upload-sourcemaps dist/assets

安全提醒：确保构建后删除 .map 文件，防止用户下载源码：
// .sentryclirc
[auth]
token=YOUR_TOKEN
或在 vite.config.ts 中：build.sourcemap: 'hidden'

Source Map 安全——生产不暴露

推荐流程：

构建生成 .js.map 文件
Sentry 插件自动上传
删除 .map 文件

// vite.config.ts
export default defineConfig({
  build: {
    sourcemap: true,  // 构建时生成
  },
  plugins: [
    sentryVitePlugin({ ... }),
    {
      name: 'remove-sourcemaps',
      closeBundle() {
        // 上传后删除 .map，防止用户下载
        fs.rmSync('dist/assets/*.map', { force: true });
      },
    },
  ],
});

Session Replay

录制用户的点击、滚动、输入等操作，在错误发生时回放：

new Sentry.Replay({
  maskAllText: false,     // 掩码文字（默认 true，保护隐私）
  blockAllMedia: false,   // 阻止媒体加载
  networkDetailAllowUrls: [import.meta.env.VITE_API_BASE],
});

本地开发环境屏蔽

避免开发环境污染 Sentry：

Sentry.init({
  enabled: import.meta.env.PROD,   // 仅生产启用
  // 或
  beforeSend(event) {
    if (import.meta.env.DEV) return null; // 丢弃开发环境的错误
    return event;
  },
});

与 React Router 集成

import { createRoutesFromChildren, matchRoutes, useLocation, useNavigationType } from 'react-router-dom';

Sentry.init({
  integrations: [
    new Sentry.BrowserTracing({
      routingInstrumentation: Sentry.reactRouterV6Instrumentation(
        useEffect,
        useLocation,
        useNavigationType,
        createRoutesFromChildren,
        matchRoutes,
      ),
    }),
  ],
});

监控面板关键指标

部署后在 Sentry UI 重点关注：

面板	关注点
Issues	新增错误排名、影响用户数、首次/最近发生时间
Performance	LCP / FCP / FID / TTFB 等 Web Vitals、慢 Transaction
Releases	每次发布后的错误对比，判断是否引入新 Bug
Dashboards	自定义看板：错误率趋势、Top 错误、用户分布

小结

环境	必须配置
开发	`enabled: false` 或 `beforeSend` 过滤
预发	开启（验证 Source Map）、`tracesSampleRate: 0.5`
生产	`tracesSampleRate: 0.2`、`Replay` 按需、`ignoreErrors` 过滤噪声

Sentry 的核心价值在于：错误 → 上下文 → 源码 的一键链路，让线上 Bug 从"用户说打不开了"变为"开发直接看到报错行号+操作回放"。

上一节：权限组件设计下一节：React 源码架构解析