Sentry 接入实践
🎯 引言
前面几篇我们手动实现了错误采集和上报，但真到生产环境，你还要自己搭接收服务、做错误聚合、配告警通知，维护成本不低。更常见的做法是接入现成的监控平台，Sentry 就是这类平台中主流的一个：装一个 SDK，错误自动捕获并上报，后台网页上直接看「哪个错误、影响了多少用户、堆栈是什么」，还能配置出错通知。
学完本篇，你将能够：
- 在 Vue3 项目中初始化 Sentry，并主动上报一条测试错误验证链路。
- 上传 source map，把压缩后的堆栈还原成源码行列号。
- 配置一条基础的告警规则，错误发生时及时收到通知。
🧱 Sentry 是什么
Sentry 由两部分组成：SDK（装在你项目里的采集端，自动捕获运行时错误、Promise 未捕获异常等）和后台服务（接收数据，把相同错误聚合成一个 Issue，展示影响面和完整堆栈，并提供告警）。可以把它理解成一家托管安防公司：摄像头（SDK）装在你店里，录像实时传到它的后台，它帮你归类，发现异常主动打电话（告警）通知你，省得你自己存带子、翻带子。
🧱 接入 Sentry
接入分两步：控制台创建项目拿 DSN，代码里初始化 SDK。先在 Sentry 官网注册登录，新建项目，平台类型选 Vue，创建后得到一串 DSN（上报地址 + 项目身份标识），形如 https://xxxxx@o123.ingest.sentry.io/456。
然后安装 SDK 并在应用入口初始化，以下基于 Node.js v22 + @sentry/vue v9.x 验证：
pnpm add @sentry/vue
import { createApp } from 'vue';
import * as Sentry from '@sentry/vue';
import App from './App.vue';
const app = createApp(App);
Sentry.init({
app, // 传入 Vue 应用实例，SDK 会自动捕获组件内的错误
dsn: 'https://xxxxx@o123.ingest.sentry.io/456', // 换成你自己的 DSN
environment: import.meta.env.MODE, // 区分 development / production 环境
});
app.mount('#app');
app 必须传入，SDK 借此挂钩 Vue 的错误处理机制，组件内的错误才能被自动捕获。最后验证链路：临时加一个会 throw new Error('Sentry 测试错误') 的按钮，点击后 Sentry 后台的 Issues 列表应出现这条错误，确认后删掉按钮。
💡 区分环境与控制上报量
本地开发时错误不断，如果也报上来，线上数据就被淹没了。两个常用做法：用 environment 打标签便于后台过滤（上面已配置），以及只在生产环境启用 SDK（本地报错照常打在控制台，也节省按事件计费的额度）：
if (import.meta.env.PROD) {
Sentry.init({
app,
dsn: 'https://xxxxx@o123.ingest.sentry.io/456',
environment: import.meta.env.MODE,
});
}
🧱 Source Map 与错误定位
接入后你会发现后台堆栈显示的是 assets/index-Bx3kP9.js:1:18432，而不是源码位置：线上跑的是打包压缩后的代码，报错的行列号自然指向压缩产物。打包时生成的 source map 记录了压缩代码和源码的位置对应关系，把它上传给 Sentry，后台就能自动还原堆栈。以上传插件为例，以下基于 Node.js v22 + @sentry/vite-plugin v3.x 验证：
pnpm add -D @sentry/vite-plugin
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { sentryVitePlugin } from '@sentry/vite-plugin';
export default defineConfig({
plugins: [
vue(),
// 放在插件列表末尾：构建结束时上传本次产物的 source map
sentryVitePlugin({
org: '你的组织名',
project: '你的项目名',
authToken: process.env.SENTRY_AUTH_TOKEN, // 放在环境变量里，不要写死
}),
],
build: {
sourcemap: true, // 让 Vite 构建时生成 source map 文件
},
});
两个关键点：build.sourcemap: true 先让构建产出 source map，插件才有东西可传；authToken 是上传凭证，在 Sentry 控制台生成，务必通过环境变量注入，不能提交进仓库。配置好后重新构建部署，新上报的堆栈就会显示成 src/views/User.vue:42 这样的源码位置。
.map 文件（插件提供相应选项），只让 Sentry 后台持有它。🧱 告警与通知
数据收上来只是第一步，出了问题能马上知道才是监控的闭环。Sentry 的告警通过「规则」配置：触发条件 + 通知渠道。在项目的 Alerts 页面新建规则：
- 触发条件：常用起点是「出现新 Issue 时触发」，适合上线初期快速发现新错误；也可以按「某 Issue 单位时间内发生次数超过阈值」监控已有错误的爆发。
- 通知渠道：邮箱，或接入 Slack、钉钉、飞书等群机器人推送到团队群。
注意告警不是越多越好：每次小错误都推送，团队很快会对告警麻木，严重问题反而被忽略。稳妥的做法是先用宽松的规则（只告警新 Issue 和错误量突增），观察一两周后按误报情况收紧。告警策略的更多设计思路下一篇「日志与告警」会专门展开。
🧾 小节总结
- Sentry = 采集 SDK + 托管后台：自动捕获错误、聚合成 Issue、提供告警，省掉自建采集服务的成本。
- 接入两步：控制台创建项目拿 DSN，代码里
Sentry.init({ app, dsn })。 - 用
environment区分环境，且只在生产环境启用 SDK，避免开发噪音淹没线上数据。 - 上传 source map 后压缩堆栈才能还原成源码行列号；
.map文件不要公开到线上。 - 告警规则 = 触发条件 + 通知渠道，从宽松开始逐步收紧，避免告警轰炸。
❓ 知识问答
Q1：DSN 泄露了会有危险吗？
A：DSN 本来就写在前端代码里，任何人都能看到，不算保密凭证。风险是别人可能用你的 DSN 上报垃圾数据，可在后台设置允许的域名缓解。真正要保密的是上传 source map 的 authToken。
Q2：接入 Sentry 后，还需要自己写 window.onerror 吗？
A：一般不需要，SDK 已覆盖常见错误场景，再手写容易重复上报。但 SDK 管不到的业务埋点和特殊采集逻辑，仍然要自己写。
Q3：本地开发时为什么看不到数据上报？
A：常见两个原因：只在生产环境调用了 Sentry.init，本地没启用；或浏览器广告拦截插件拦掉了上报请求。可临时去掉环境判断，再看网络面板确认请求是否发出。
Q4：后台堆栈还是压缩后的，怎么办？
A：先确认上传了 source map（不传则堆栈只能停留在压缩位置），再按顺序排查：build.sourcemap 是否打开；插件的 org、project、authToken 是否正确；上传的 source map 和线上代码是否同一次构建的产物，版本对不上也会还原失败。
🧪 小练习
练习一：给下面这段入口代码补上环境处理：只在生产环境启用 Sentry，并带上环境标签。
import { createApp } from 'vue';
import * as Sentry from '@sentry/vue';
import App from './App.vue';
const app = createApp(App);
// 请在这里编写代码：仅生产环境初始化 Sentry，并设置 environment
app.mount('#app');
练习二：一位同学在 Sentry 后台看到的错误堆栈是 assets/index-Bx3kP9.js:1:18432，无法对应到源码。请写出他的项目里可能缺少的两处配置，并说明各自的作用：
// 请在这里编写代码（或文字说明）：缺少的配置一
// 请在这里编写代码（或文字说明）：缺少的配置二
完成后想想：如果他把 authToken 直接写在 vite.config.js 里提交到仓库，会有什么风险？
🎉 恭喜你已经掌握 Sentry 接入技能啦！下一篇是本课程的收尾篇「日志与告警」，我们把日志分级和告警策略补完整。