Sentry 前端监控：实时错误追踪与性能监控

FreeGuideOnline 最新 2026-06-15

Sentry 前端监控：实时错误追踪与性能监控

Sentry 是一个开源的全栈错误追踪与性能监控平台，支持几乎所有主流语言和框架。本教程专为前端开发者设计，从零开始搭建一套现代化、可落地的 Sentry 监控体系，涵盖错误捕获、性能分析、源码映射以及发布管理，兼顾实时性与可追溯性。

为什么选择 Sentry

在传统开发中，线上报错只能依赖 window.onerror 或 console 日志，难以定位复现路径与影响范围。Sentry 提供：

完整的错误上下文：面包屑、用户行为回放、网络请求、设备环境等。
自动进行错误分组：根据堆栈指纹聚合相似问题，避免重复工单。
性能监控一体化：无需额外工具即可度量 LCP、FID、页面加载瀑布流。
与源码映射深度集成：压缩后的生产代码可直接还原为原始行号。
团队协作与告警：支持邮件、Slack、钉钉等通知，可与 JIRA、GitHub 联动。

环境准备

你需要具备：

一个 Sentry 账号（可通过 sentry.io 免费注册）。
一个前端项目（React、Vue、Angular 或原生 JS 均可，本教程以 Vanilla JS + Webpack 为例，框架集成方式将单独说明）。
Node.js 环境用于安装 SDK 与演示构建。

Sentry 提供 SaaS 与自部署两种模式，初学者推荐直接使用官方云服务，免费额度内每月5000个错误事件通常足够。

创建 Sentry 项目

登录 Sentry 后，点击 创建项目 (Create Project)。
平台（Platform）选择 JavaScript（或具体框架，如 React）。
项目创建完毕后，Sentry 会生成一个 dsn (Data Source Name)，格式为：
```
https://<public_key>@o<org_id>.ingest.sentry.io/<project_id>
```
这个 dsn 是 Sentry 识别项目的唯一凭证，需要在前端代码中配置。

安全提示：dsn 必须出现在客户端，因此请将其保存在环境变量而非仓库明文，通过构建时注入。

安装 SDK

npm 方式（推荐）

npm install @sentry/browser @sentry/tracing --save

CDN 方式（适用于无构建工具的项目）

<script src="https://browser.sentry-cdn.com/7.x.x/bundle.tracing.min.js"
        integrity="sha384-..."
        crossorigin="anonymous"></script>

版本号请参照 Sentry 官方文档获取最新 CDN 链接。

本教程后续以 npm 方式讲解。

初始化 Sentry

在应用主入口文件（如 index.js 或 main.js）中引入并初始化：

import * as Sentry from "@sentry/browser";
import { BrowserTracing } from "@sentry/tracing";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [new BrowserTracing()],

  // 设置采样率（生产环境建议降低以控制用量）
  tracesSampleRate: 1.0,  // 100% 采集性能事务，可调低至 0.1
  // 调试模式，开发时开启
  debug: false,
  // 发布版本，用于关联源码映射
  release: "my-project@1.0.0",
  // 环境（development / staging / production）
  environment: "production",
});

完成初始化后，Sentry 将自动捕获全局未处理的 JavaScript 错误（uncaught exception）和未处理的 Promise 拒绝（unhandledrejection）。

验证安装

建议用一个简单的按钮触发错误事件，以确保 SDK 正常工作：

<button id="errorBtn">触发测试错误</button>
<script>
  document.getElementById('errorBtn').addEventListener('click', () => {
    throw new Error('Sentry 前端测试错误');
  });
</script>

点击按钮后，打开 Sentry 项目主页，在 Issues 中即可看到一条新错误，并且包含完整堆栈、用户代理等上下文。

手动捕获错误

除了自动捕获，Sentry 提供丰富的 API 以满足精细控制需求。

捕获普通错误

try {
  someRiskyOperation();
} catch (error) {
  Sentry.captureException(error);
}

捕获自定义消息

Sentry.captureMessage('Something went wrong', 'warning');

级别可选：'fatal', 'error', 'warning', 'info', 'debug'。

添加上下文信息

通过 scope 可临时附加用户、标签、附加数据：

Sentry.withScope(scope => {
  scope.setUser({ id: '123', email: 'user@example.com' });
  scope.setTag('page', '/dashboard');
  scope.setExtra('custom_data', { plan: 'pro' });
  Sentry.captureException(new Error('带上下文的错误'));
});

setTag 适合用于索引、过滤；setExtra 适合存储非结构化的调试数据。

添加面包屑 (Breadcrumbs)

面包屑记录了事件发生前的一系列操作，帮助重现用户路径。Sentry 会自动记录点击、XHR 请求、控制台日志等，你也可以手动追加：

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

当错误发生时，这些面包屑将按时间倒序呈现在事件详情页，极大提升定位效率。

源码映射 (Source Maps)

生产环境的 JavaScript 通常经过压缩混淆，需要上传 source map 才能看到原始代码位置。

生成 source map

确保你的构建工具（如 Webpack）开启了 source map 生成：

// webpack.config.js
module.exports = {
  devtool: 'source-map', // 或 'hidden-source-map'
  // ...
};

推荐使用 hidden-source-map：只生成 .map 文件，但不在打包后的 .js 文件中添加 sourceMappingURL 注释，避免客户端直接暴露源码。

上传 source map 到 Sentry

使用 @sentry/webpack-plugin 配合构建自动上传：

安装插件：

npm install @sentry/webpack-plugin --save-dev

在 Webpack 配置中引入：

const SentryWebpackPlugin = require('@sentry/webpack-plugin');

module.exports = {
  // ...其他配置
  plugins: [
    new SentryWebpackPlugin({
      // 对应 Sentry 项目的 auth token（需创建对应用户 token）
      authToken: process.env.SENTRY_AUTH_TOKEN,
      org: 'your-org-slug',
      project: 'your-project-slug',
      include: './dist',               // 打包输出目录
      ignore: ['node_modules'],
      release: 'my-project@1.0.0',    // 必须与 init 中一致
      cleanArtifacts: true,
    }),
  ],
};

在构建时确保 SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT 等环境变量已设置。

上传成功后，Sentry 会自动关联每个错误事件的源码映射，详情页将显示原始代码行，开发体验极大提升。

性能监控 (Tracing)

Sentry Tracing 基于 W3C Trace Context 标准，可追踪前端事务，包括：

页面加载 (pageload)
路由切换 (navigation)
自定义事务

自动页面加载性能

初始化时集成了 BrowserTracing，并设置 tracesSampleRate，Sentry 会自动捕获页面加载性能数据，生成 Performance 面板中的瀑布图，包含 TTFB、FP、FCP、LCP、FID 等 Web Vitals。

自定义事务

用于追踪特定操作（如按钮点击处理、API 调用）：

const transaction = Sentry.startTransaction({ name: 'custom-transaction' });
const span = transaction.startChild({ op: 'task', description: '算费' });

doExpensiveWork()
  .then(() => {
    span.finish(); // 完成当前 span
    transaction.finish(); // 结束事务
  });

每个事务可包含多个 span（时间片段），形成调用树，便于分析性能瓶颈。

框架集成指南

React

npm install @sentry/react @sentry/tracing

在 index.js 中：

import * as Sentry from "@sentry/react";
import { BrowserTracing } from "@sentry/tracing";

Sentry.init({
  dsn: "...",
  integrations: [new BrowserTracing()],
  tracesSampleRate: 1.0,
});

ReactDOM.render(<App />, document.getElementById('root'));

使用 ErrorBoundary 组件捕获 React 渲染错误：

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

<Sentry.ErrorBoundary fallback={<p>出错了</p>}>
  <App />
</Sentry.ErrorBoundary>

Vue 2/3

npm install @sentry/vue @sentry/tracing

import * as Sentry from "@sentry/vue";
import { BrowserTracing } from "@sentry/tracing";

const app = createApp(App);
Sentry.init({
  app,
  dsn: "...",
  integrations: [new BrowserTracing()],
  tracesSampleRate: 1.0,
});
app.mount('#app');

Sentry 会自动集成 Vue 的错误处理器，同时捕获组件渲染错误。

Angular

npm install @sentry/angular @sentry/tracing

在 app.module.ts 中导入 Sentry.createErrorHandler()，详细步骤参照官方文档。

环境与发布管理

配置 release 版本

每次构建时指定唯一的 release 标识（如 Git commit hash 或版本号），并确保上传 source map 时使用相同名称。

Sentry.init({
  release: 'my-app@1.2.3',
  // ...
});

通过 CLI 或插件自动注入

可以使用 Webpack DefinePlugin 或环境变量注入：

new webpack.DefinePlugin({
  'process.env.SENTRY_RELEASE': JSON.stringify('my-app@1.2.3'),
});

关联提交信息

Sentry 可通过 GitHub/GitLab 集成，将 release 与 commit 绑定，实现错误→提交→开发者的精准追踪。在 Settings > Integrations 中配置即可。

过滤与忽略常见噪声

有些错误无需关注，通过几种方式排除：

`ignoreErrors` 选项

Sentry.init({
  ignoreErrors: [
    /Script error\./,
    'ResizeObserver loop limit exceeded',
  ],
});

`beforeSend` 钩子

可完全拦截事件，修改或丢弃：

Sentry.init({
  beforeSend(event, hint) {
    // 丢弃某类错误
    if (event.exception?.values?.[0]?.type === 'MyCustomIgnoredError') {
      return null;
    }
    // 可修改 event
    return event;
  },
});

自定义采样率

对错误事件进行采样以控制发送量：

Sentry.init({
  sampleRate: 0.5, // 仅发送 50% 的错误事件
});

高级用法：自定义传输层

默认通过 HTTP 发送事件，若网络受限，可自定义传输（如日志到控制台）：

import { createTransport } from '@sentry/core';

const customTransport = createTransport({}, (event) => {
  console.log('Sentry event:', event);
  return Promise.resolve({ status: 'success' });
});

Sentry.init({
  dsn: '...',
  transport: customTransport,
});

最佳实践与避坑指南

生产环境降低性能采样率：tracesSampleRate 设为 0.1~0.3 足够分析整体趋势，避免性能事件占用过高配额。
合理使用面包屑：避免记录敏感信息（密码、token），Sentry 默认可滤除密码字段。
隐藏生产调试信息：debug: false 且确保不会泄露内部路径。
始终上传 source map：否则压缩错误堆栈近乎不可读。
结合 CI/CD 自动推送 release：每次部署自动生成 release 并上传 map，关联 commit。
利用标签与自定义上下文：标记用户付费状态、版本、渠道等，便于筛选问题分布。
定期回顾 Issues：Sentry 提供回归检测、问题分配等功能，推动 bug 清零。

常见问题排查

现象	可能原因	解决方案
错误未上报	`dsn` 错误或网络拦截	打开浏览器网络面板，检查 `sentry_key` 请求；使用 `debug: true` 查看日志
堆栈混淆	未上传 source map	确认 `release` 一致且上传成功，在 Sentry 设置内查看 Artifacts
性能数据缺失	`tracesSampleRate` 为 0 或网络问题	检查采样率，确保浏览器支持 Performance API
大量重复错误	错误分组策略不理想	在项目设置中配置堆栈指纹规则，或使用 `fingerprint` 属性自定义分组

Sentry 前端监控：实时错误追踪与性能监控

为什么选择 Sentry

环境准备

创建 Sentry 项目

安装 SDK

npm 方式（推荐）

CDN 方式（适用于无构建工具的项目）

初始化 Sentry

验证安装

手动捕获错误

捕获普通错误

捕获自定义消息

添加上下文信息

添加面包屑 (Breadcrumbs)

源码映射 (Source Maps)

生成 source map

上传 source map 到 Sentry

性能监控 (Tracing)

自动页面加载性能

自定义事务

框架集成指南

React

Vue 2/3

Angular

环境与发布管理

配置 release 版本

通过 CLI 或插件自动注入

关联提交信息

过滤与忽略常见噪声

ignoreErrors 选项

beforeSend 钩子

自定义采样率

高级用法：自定义传输层

最佳实践与避坑指南

常见问题排查

更多资源

`ignoreErrors` 选项

`beforeSend` 钩子