前端错误监控：Sentry接入与source map

前端错误监控接入 Sentry 的核心只有三件事：装 SDK 并在初始化时写死 release、构建时用插件把 source map 上传到同一个 release、上线后让 Sentry 用这份 map 把压缩代码的堆栈还原成源码行号。这三步里任何一步对不上，你在 Sentry 看到的就只是 a.min.js:1:48213 这种没法定位的乱码，监控等于白装。

Sentry 前端接入要写哪几行代码？

结论：初始化时 dsn、release、environment 三个字段必须写全，其中 release 是后续 source map 能不能对上的唯一钥匙。

以 @sentry/react 为例（Vue 用 @sentry/vue，纯浏览器用 @sentry/browser，用法一致）：

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

Sentry.init({
  dsn: 'https://xxx@o123.ingest.sentry.io/456',
  release: `web@${process.env.APP_VERSION}`, // 例如 web@1.8.3
  environment: process.env.NODE_ENV,
  sampleRate: 1.0,          // 错误采样率，0~1
  tracesSampleRate: 0.2,    // 性能采样率，按流量成本调
});

release 推荐用「项目名@版本号」格式，并且这个版本号要从 CI 注入（git describe --tags 或 package.json 的 version），不能在本地硬编码。Sentry v8 起性能监控集成用 browserTracingIntegration()，v7 里是 new BrowserTracing() 塞进 integrations 数组，升级时容易踩坑，SDK 大版本升级前后要各跑一次错误测试。

为什么前端一定要上传 source map？

结论：生产构建产物是压缩混淆后的代码，没有 source map，Sentry 只能告诉你错误发生在第 1 行第 48213 列，拿不到真实文件、函数名和行号。

Sentry 的解析逻辑是「构建时上传」而不是「运行时抓取」——它不会去访问你线上的 .map 文件，而是要求你在发布阶段把 map 传到它的服务器，按 release + 文件路径索引。所以 source map 上传是发布流程的一环，不是可选项。

同时建议生产环境用 hidden-source-map（webpack）或 sourcemap: 'hidden'（Vite），它的行为是：照常生成 .map 文件，但不在 JS 末尾写 //# sourceMappingURL= 注释。这样浏览器 DevTools 不会自动加载源码，Sentry 又能正常解析，兼顾了排查效率与源码泄露风险。

source map 怎么上传？Webpack 和 Vite 分别怎么配？

结论：优先用官方构建插件自动上传，别手动传；插件会在打包结束那一刻把 map 连同 release 一起提交，最不容易错位。

Webpack 用 @sentry/webpack-plugin：

new SentryWebpackPlugin({
  org: 'your-org',
  project: 'your-project',
  authToken: process.env.SENTRY_AUTH_TOKEN,
  release: { name: `web@${process.env.APP_VERSION}` },
  sourcemaps: { assets: './dist/**', deleteFilesAfterUpload: './dist/**/*.map' },
})

Vite 用 @sentry/vite-plugin，配置项同名。deleteFilesAfterUpload 会在上传成功后删掉本地 map 文件，避免 map 被打进部署包又被公网访问到。

手动方案（CDN 上传、非标准构建时用）是 sentry-cli：

sentry-cli releases new web@1.8.3
sentry-cli releases files web@1.8.3 upload-sourcemaps ./dist \
  --url-prefix '~/static/js' --rewrite
sentry-cli releases finalize web@1.8.3

--url-prefix 必须和浏览器实际请求 JS 的路径前缀一致（~/ 代表站点根）。漏掉这一步会得到「Artifact not found」或堆栈依然未解析的结果。

source map 上传了但错误还是没法解析，怎么排查？

结论：九成问题出在四处不一致，按顺序查完基本能定位。

1. release 不一致：前端 Sentry.init 里的 release 字符串必须和上传时的 --release 或插件里的 release 逐字符相同，多一个空格都算两个版本。
2. url-prefix 不匹配：--url-prefix 要对应 CDN 或 publicPath，例如静态资源放在 https://cdn.x.com/js/ 就写 --url-prefix 'https://cdn.x.com/js'。
3. devtool 类型不对：必须用 source-map 或 hidden-source-map，eval、cheap-eval-source-map 这类生成的内联 map 无法被解析。
4. 漏了 finalize：手动上传时没执行 sentry-cli releases finalize，release 一直处于草稿状态，事件不会挂到它上面。

另外，同一 release 下如果有多份产物（比如主包和懒加载 chunk），可以在插件或 CLI 里设置 dist 字段区分，避免不同构建的同名文件互相覆盖。

除了 Sentry，还需要自己监听什么？

结论：Sentry 默认能自动捕获 window.onerror 和 unhandledrejection，但有两类错误它抓不全，需要额外处理。

第一类是跨域脚本错误。第三方 CDN 上的 JS 报错，浏览器出于安全策略只给 Script error.，没有堆栈。解法是给 <script> 加 crossorigin="anonymous"，同时 CDN 返回 Access-Control-Allow-Origin。

第二类是资源加载失败（图片、字体、接口 404）。这类要走 window.addEventListener('error', fn, true) 的捕获阶段，再配合 Sentry.captureException 上报。白屏检测同理，常见做法是在根节点挂载后检查 document.querySelector('#app').innerHTML 是否为空，为空时主动上报一条高优先级事件。

回到主线：先固定 release，再让构建插件把 source map 传到同一个 release，最后用排查清单兜底。这三点做扎实，前端错误监控才算真正可用。