当前位置： 首页 > news >正文

前端错误监控实践：Sentry 在 Vite + Vue 项目中的配置与原理详解

news 2025/10/21 7:24:07

一、Sentry 的工作原理

Sentry 是一套用于错误监控与性能分析的系统。前端接入 Sentry 后，核心流程可以抽象为三步：

  1. 捕获：SDK 在运行时通过挂载全局监听（如 window.onerror、window.onunhandledrejection、框架层面的错误钩子）或手动调用 Sentry.captureException、Sentry.captureMessage 等 API 收集异常信息、上下文（URL、用户、环境、breadcrumbs 等）。

  2. 上报：SDK 将错误事件（包含压缩后的位置：文件名、行号、列号、stacktrace）以及上下文通过 HTTP 请求发送到 Sentry 服务端（由 DSN 标识）。

  3. 还原与展示：Sentry 服务端（或在 UI 上）借助 Source Map，将压缩后的位置信息还原为原始源码位置，展示文件名、函数、源代码行，便于开发定位与排查。

另外，Sentry 支持 Release、环境（environment）、Tag、User 等维度，用于聚合、筛选与告警触发。

本篇文章使用的 sentry 版本如下

"@sentry/vite-plugin": "4.2.0",

"@sentry/vue": "10.7.0",

二、在 Vite + Vue 中配置 sentry 的最佳实践

2.1 打包并上传 sourmap

  1. 生成 Source Map（打包时）：
    在 vite.config.ts 中开启：

    import { sentryVitePlugin } from '@sentry/vite-plugin'
import { defineConfig, loadEnv } from 'vite'// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {// 获取各个环境的配置const env = loadEnv(mode, process.cwd())return {plugins: [sentryVitePlugin({debug: true, // 开启打印 sentry 上传日志，调试用org: 'your org',project: 'your project',url: 'your url',authToken: env.VITE_SENTRY_AUTH_TOKEN, //必须sourcemaps: {ignore: './node_modules/**/*',filesToDeleteAfterUpload: './dist/**/*.map' //打包上传map后，删除所有map文件}})],build: {// 注意生成后要删除，不要上传到公网sourcemap: true}}
})

  2. 切勿将 Source Map 上传到公开的 OSS/CDN：

    • Source Map 含有源码映射，会暴露源码或内部实现细节；

    • 正确做法是把 Source Map 上传到 Sentry 并在部署产物中移除或不上传到公共文件服务器。

    • 所以这里是用了 filesToDeleteAfterUpload 字段，在 vite 打包生成map并上传之后之后就删除源map文，如果 authToken 失效，导致的上传失败，也可以正常删除map文件【至少我用的版本可以，具体可以自己开启 debug: true, 看打包过程中生成的日志】

不同版本的 @sentry/vite-plugin 配置项可能略有差异，建议查阅对应插件版本的 README 做最终确认。

2.3 在 mian.ts 中初始化 sentry

import { createApp } from 'vue'
import App from './App.vue'
import * as Sentry from '@sentry/vue'const app = createApp(App)
Sentry.init({app,dsn: 'your dsn', // 每个项目都有一个对应的 dsn, 在 sentry 后台可以找到integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()],environment: import.meta.env.VITE_NODE_ENV
})
app.mount('#app')

三、重要的 sentry 插件配置项

3.1 使用 debug: true 调试

在 sentryVitePlugin 插件中配置 debug: true 可以查看在vite build 过程中 sentry 插件的执行日志。

map文件生成日志

map 文件上传日志

map 文件删除日志

这里我们可以测试一下，随便写一个 authToken ,再打包，会在 map 上传 sentry 阶段报错，如下图

但是我们会发现后面依旧有删除 map 文件的日志，所以可以确认即便是上传 sentry失败了，也会执行 filesToDeleteAfterUpload: true 的配置。即便是没有删除 map 文件的日志，dist文件夹中的map 文件也没有了。【当然了，具体是否会删除还是取决于你使用的插件的版本的，可以自己实践一下，或者看一下版本对应的readme 说明】

3.2 上传 sourcemap 使用的 authToken

3.2.1 authToken 的作用

  • 作用：authToken 用于通过 Sentry 的 API 进行授权操作（比如创建 release、上传 Source Map、设置 commit 信息等）。构建/CI 在上传 artifacts（sourcemap）时需要该 token。

  • 获取步骤：

    1. 登录 Sentry；

    2. 进入账户设置（User Settings）→ Auth Tokens；

    3. 新建 Token，勾选合适的权限（常用 project:releases、org:read 等，按最小权限原则授权）。

  • 是否会失效：Token 在创建后不会自动过期，但可以手动撤销或删除。若 Token 被撤销或权限变更，CI 上传将失败并返回相应错误。

  • 安全性建议：

    • 把 token 放在 CI 的 Secret 或项目根的 .env（但 .env 不应提交到仓库）；

    • 在本地开发环境尽量使用只读或最小权限 token；

    • 在 CI 中使用环境变量 SENTRY_AUTH_TOKEN，避免明文出现在仓库或日志中。

3.3.2 如何判断 authToken 是否有效

可以使用命令行工具执行下面命令，前面 <your demain url> 写你配置中的 url，<your token> 写你的 authToken.

api/0/ → 这是 Sentry 官方 API 的 版本号和前缀，对于 Sentry 版本 0 API 来说是固定的（即 api/0/ 是固定的，后面跟具体资源路径）。

curl <your demain url>api/0  \-H "Authorization: Bearer <your token>"

如果 token 无效会返回  {"detail":"Invalid org token"}

3.3.3 如果 authToken 无效或丢失，会发生什么？

  • 如果 authToken 错误、过期或无效（比如权限不足、token 配置错误等），
    上传 sourcemap 会失败；

  • Sentry CLI 会在上传阶段报错（例如 error: API request failed (401 Unauthorized)）；

  • 但打包过程本身不会中断，也就是说：

    • Vite 打包结果（JS/CSS/HTML）仍会正常生成；

    • 会删除 .map 文件；【具体取决于你用的sentry插件的版本号】

    • 控制台会打印上传失败的错误日志；

3.3 release 版本号/版本标识

只有在上传到 Sentry 的 Source Map 与上报事件的 release  匹配时，才会能把报错精确到源码的某个行数。

在默认的情况下 release 一般是最后一个代码提交的 commit 的哈希值，如下图，我们可以发现这个 release 和 git log 打印出来的最新的一个提交相同。

3.3.1 自定义 release

import { sentryVitePlugin } from '@sentry/vite-plugin'
import { defineConfig, loadEnv } from 'vite'// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {// 获取各个环境的配置const env = loadEnv(mode, process.cwd())return {plugins: [sentryVitePlugin({debug: true, // 开启打印 sentry 上传日志，调试用org: 'your org',project: 'your project',url: 'your url',authToken: env.VITE_SENTRY_AUTH_TOKEN, //必须release: {name: 'my_release' // 自定义版本号 release},sourcemaps: {ignore: './node_modules/**/*',filesToDeleteAfterUpload: './dist/**/*.map' //打包上传map后，删除所有map文件}})],build: {// 注意生成后要删除，不要上传到公网sourcemap: true}}
})

在 sentry 插件中配置之后，打包出来的 release 那么就成我们配置的了。

四、sentry.init 的原理

在 Vue 3 + Vite 项目中，推荐在入口文件 main.ts 里初始化 Sentry SDK，让 SDK 在应用整个生命周期内生效。

示例：

import { createApp } from 'vue'
import App from './App.vue'
import * as Sentry from '@sentry/vue'const app = createApp(App)
Sentry.init({app,dsn: 'your dsn', // 每个项目都有一个对应的 dsn, 在 sentry 后台可以找到integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()],environment: import.meta.env.VITE_NODE_ENV
})
app.mount('#app')

Sentry.init 的关键工作：

  1. 注册全局错误捕获：将 Vue 的 error handler、window.onerror、unhandledrejection 等挂接到 Sentry 的捕获链路；

  2. 配置上下文与默认信息：environment、release、tags、breadcrumbs 等会随事件上报；

  3. 初始化集成（integrations）：例如 BrowserTracing（性能追踪）、Replay（会话回放）等，集成会在浏览器中额外收集导航性能、路由变更、用户会话等；

  4. 暴露 API：如 Sentry.captureException, Sentry.setUser, Sentry.setTag，供代码其他位置手动上报或补充上下文。

  • release 要与打包时上传 sourcemap 的 release 完全一致，否则 Sentry 无法正确匹配并还原源码行号；

  • 如果你不上传 map 文件到 sentry 服务器，那么 sentry 捕获的错误智能展示压缩后行号。

五、将 sentry 捕获的错误推送到钉钉报警群

我们可以通过配置告警规则来把 sentry 捕获的错误推送到钉钉报警群。

但是 Sentry 上能看到事件，不代表一定会触发告警推送到第三方（如钉钉）。原因在于 Sentry 的事件上报和告警规则（Alert Rules）是两套机制：

  • 事件上报：任何被 SDK 捕获并上报的异常都会在 Sentry 项目中产生 event/issue。

  • 告警推送：需要在 Sentry 项目中单独配置 Alert Rules，指定何种条件下触发（例如新建 Issue、Issue 回归、事件速率阈值等），并指定通知渠道（邮箱、Slack、Webhook、DingTalk 等）。

要把错误推送到钉钉，需要：

  1. 在钉钉群里创建自定义机器人并获取 Webhook；

  2. 在 Sentry 中配置一个通知集成（Webhook / DingTalk 插件或使用通用 webhook）；

  3. 在项目的 Alerts → Alert Rules 中创建规则并指定该通知渠道。

六、总结

建议把 Sentry 集成流程纳入 CI/CD 的固定步骤，示例顺序如下：

  1. CI 拉取代码，生成 RELEASE_VERSION（用 commit hash）；

  2. 安装依赖并执行 vite build（sourcemap: true）；

  3. 使用 @sentry/vite-plugin（debug: true 临时启用以便观察）上传 Source Map 并用 filesToDeleteAfterUpload 删除 .map；

  4. 验证上传日志无误后，将产物（不含 .map）发布到 OSS/CDN；

  5. 运行时在 main.ts 中 Sentry.init({ release: RELEASE_VERSION })，确保上报事件能被还原；

  6. 在 Sentry 中配置 Alert Rules 与钉钉 Webhook，搭建告警闭环。

http://www.dtcms.com/a/506828.html

相关文章：

  • Marin说PCB之GMSL2网络中AC电容前端控制100欧姆和不做差分100欧姆的区别？
  • Oracle 数据库 Schema 备份与导入全攻略
  • PySide6 使用搜索引擎搜索 多类实现
  • 东莞市外贸网站建设公司自己做投票的网站
  • 网站建设的基础服务器专业建站公司的业务内容
  • 【iOS】KVC 与 KVO 的基本了解与使用
  • Day66 DHT11温湿度传感器驱动开发与单总线通信协议
  • 【代码管理】在本地使用github和gitee之后，可能存在冲突，导致再次提交代码时提示Couldn‘t connect to server
  • bash:**:pip:***python: 错误的解释器: 没有那个文件或目录
  • OpenCV(十二)：Mat
  • iOS 智能应用开发实践：从模型集成到场景化交互
  • 更好的网站制作系统平台
  • 佛山市手机网站建设网站建设管理工作情况的通报
  • ThinkPad 安装 Ubuntu 系统教程
  • 《未来的 AI 操作系统（四）——AgentOS 的内核设计：调度、记忆与自我反思机制》
  • Platform Health Management 与 EXM/STM 的集成实现方式
  • lambda怎么遍历集合
  • 国外客户推广网站做羞羞事的网站
  • 安装好PySide6后如何找到Qt Designer(pyside6-designer.exe)可执行文件
  • EIT/ERT技术在机器人触觉传感的硬件及电路实现
  • h5游戏免费下载：公园停车
  • FPGA 49 ，Xilinx Vivado 软件术语解析（Vivado 界面常用英文字段详解，以及实际应用场景和注意事项 ）
  • 自动化漏洞利用技术颠覆传统：微软生态暴露的攻防新变局
  • Annals of Neurology | EEG‘藏宝图’：用于脑电分类、聚类与预测的语义化低维流形
  • 中小学网站建设有什么好处管理系统软件开发
  • uniapp canvas实现手写签字功能(包括重签,撤回等按钮)
  • 大语言模型如何精准调用函数—— Function Calling 系统笔记
  • 商业智能BI 浅谈数据孤岛和数据分析的发展
  • Chrome 浏览器扩展图片 提取大师
  • Uniapp微信小程序开发：修改了数据，返回父页面时，父页面数据重新加载