前端应用在用户侧运行时，可能会因为网络波动、浏览器兼容问题、代码逻辑漏洞等多种原因出现未捕获的异常，这些异常如果没有被及时记录和上报，开发者很难感知到线上问题，最终影响用户体验。搭建一套完善的错误监控与上报系统，能够帮助团队快速定位并修复线上故障，而Sentry是目前前端领域最常用的错误监控工具之一，支持自动捕获异常、收集上下文信息、提供可视化报错面板等功能。
Sentry基础环境准备
首先需要在Sentry官网注册账号并创建项目，选择项目类型为前端Web，创建完成后会得到一个唯一的DSN地址，这个地址是后续前端上报错误的核心配置项，需要妥善保存。如果是团队内部使用，也可以选择私有化部署Sentry服务，避免数据外传。
前端项目集成Sentry SDK
目前Sentry提供了官方的浏览器端SDK，我们可以通过npm安装对应的依赖包，然后在项目入口文件中完成初始化配置。
安装依赖
在项目的根目录下执行以下命令安装Sentry浏览器SDK：
npm install @sentry/browser --save
初始化配置
在项目的入口文件（比如main.js或者index.js）中添加如下初始化代码：
import * as Sentry from '@sentry/browser';
// 初始化Sentry
Sentry.init({
dsn: 'https://xxxx@ipipp.com/xxxx', // 替换为你的项目DSN地址
environment: 'production', // 设置环境标识，方便区分不同环境的报错
release: 'app@1.0.0', // 设置应用版本号，便于关联源码定位问题
// 设置需要忽略的错误类型，比如第三方脚本的无关报错
ignoreErrors: ['Script error.', 'ResizeObserver loop limit exceeded']
});
自动捕获常见前端异常
完成初始化后，Sentry会自动捕获以下几类常见的前端异常，不需要额外编写捕获代码：
- 未捕获的JavaScript运行时异常，比如调用未定义的函数、访问不存在的对象属性等
- 未处理的Promise拒绝异常，比如异步请求失败没有捕获错误的情况
- 资源加载失败错误，比如图片、脚本、样式文件加载404的情况
- 控制台输出的错误信息，通过配置也可以将console.error的内容上报到Sentry
手动上报自定义异常
除了自动捕获的异常，我们也可以在业务逻辑中手动上报特定的错误，比如接口返回的业务错误码、用户操作触发的特定异常等。
try {
// 业务逻辑代码
const result = await fetchData();
if (result.code !== 200) {
// 手动上报业务错误
Sentry.captureException(new Error(`接口返回错误: ${result.msg}`));
}
} catch (err) {
// 捕获到的异常也可以手动上报，补充额外的上下文信息
Sentry.captureException(err, {
tags: {
module: 'user_center', // 标记错误所属模块
action: 'fetch_user_info' // 标记触发错误的操作
},
extra: {
request_params: { user_id: 123 }, // 附加额外的请求参数信息
response_data: result // 附加接口返回的数据
}
});
}
补充用户上下文信息
为了更好地定位问题，我们可以给Sentry上报的错误附加用户相关的上下文信息，这样在报错面板中就能直接看到报错对应的用户信息。
// 当用户登录后，设置用户上下文
function setSentryUserContext(userInfo) {
Sentry.setUser({
id: userInfo.id,
username: userInfo.name,
email: userInfo.email
});
}
// 用户退出登录时，清除用户上下文
function clearSentryUserContext() {
Sentry.setUser(null);
}
错误上报的过滤与采样
如果前端应用的访问量较大，全量上报错误会产生较多的存储和流量成本，我们可以通过采样率配置来控制上报比例，也可以设置过滤规则忽略不需要关注的错误。
Sentry.init({
dsn: 'https://xxxx@ipipp.com/xxxx',
// 设置采样率，0.5表示只上报50%的错误
sampleRate: 0.5,
// 自定义过滤函数，返回true表示上报该错误，返回false表示忽略
beforeSend(event) {
// 忽略测试环境的错误
if (event.environment === 'test') {
return null;
}
// 忽略特定域名的资源加载错误
if (event.exception?.values?.[0]?.type === 'ResourceError') {
const resourceUrl = event.exception.values[0].value;
if (resourceUrl.includes('third-party.com')) {
return null;
}
}
return event;
}
});
源码映射配置
生产环境的前端代码通常会经过压缩混淆处理，直接上报的错误堆栈信息会是压缩后的内容，很难定位到源码的具体位置。我们可以通过上传source map文件到Sentry，让报错堆栈自动映射到源码的对应行号。
可以在项目的构建配置中添加Sentry的source map上传插件，比如使用webpack的话，可以安装@sentry/webpack-plugin，在webpack配置中添加如下内容：
const SentryWebpackPlugin = require('@sentry/webpack-plugin');
module.exports = {
// 其他webpack配置
plugins: [
new SentryWebpackPlugin({
authToken: '你的Sentry授权token',
org: '你的组织名称',
project: '你的项目名称',
// 指定需要上传的source map文件路径
include: './dist',
// 指定需要关联的release版本
release: 'app@1.0.0',
// 上传完成后是否删除本地的source map文件
deleteAfterCompile: true
})
]
};
常见问题与优化建议
在实际使用Sentry的过程中，可能会遇到一些常见问题，比如跨域资源报错被识别为Script error，这时候需要给资源标签添加crossorigin属性，同时服务端配置对应的CORS响应头。另外建议定期清理Sentry中的历史错误数据，避免存储空间占用过高，也可以针对高频错误设置告警规则，当错误触发次数超过阈值时及时通知开发团队处理。