报错只留下一句 Script error:前端监控在哪一步把现场弄丢了

前端监控不是把报错收上来就完事,而是要在事后还原一个可以复现的现场:谁、在哪个版本、哪条路由、做了什么操作、抛了什么错。浏览器默认给到的信息往往只剩一句被脱敏的 Script error.,跨域脚本、压缩后的堆栈、缺失的 release 与用户上下文,会让一条错误从可修变成不可修。最常见的误区是挂一个 window.onerror 就以为收全了,或者以为有了 sourcemap 就能自动还原。本文沿着捕获、脱敏、符号化、补上下文四步拆开信息损耗,说明资源错误为何要用捕获阶段、sendBeacon 的 64KB 限制怎么绕,并给出可执行的落地清单。

是什么

前端监控(RUM,真实用户监控)是在真实用户的浏览器里持续采集错误、性能与交互行为,再回传、聚合、告警的一套工程。错误上报只是其中一条链路,但它最容易被误解成"接一个 SDK、看一个数字"。性能侧的 LCP、CLS、INP 回答"慢不慢",错误侧回答"坏没坏",两者要按同一个 release 和路由切片才有可比性。

一句话直觉:它真正交付的不是一条报错,而是一个能复现问题的现场——谁、在哪个版本、哪条路由、做了什么操作、抛了什么错。

典型场景都很具体:首页白屏、支付按钮点了没反应、只有 iOS Safari 某个版本崩溃、发版十分钟后错误率突然抬升。这些问题的共同点是本地复现不了,只能靠线上留下的痕迹倒推。

核心原理

一次异常从发生到出现在看板上,至少要过四道关口:捕获、脱敏、符号化、补上下文。每一道都会削掉一层信息,而且后面补不回来。像事故现场取证:先封锁现场,再给物证编号,最后送实验室还原;任何一步偷懒,结论就只能靠猜。

第一道:捕获面决定你能看到多少

window.onerror 是最早的入口,它接的是脚本执行时抛出的运行时错误。资源加载失败是另一套机制:error 事件在 <img>、<script>、<link> 这些元素上触发,不冒泡到 window,必须用 window.addEventListener('error', handler, true) 在捕获阶段监听。而且这时事件对象是普通的 Event,没有 message 和 stack,只能拿到 target。

Promise 的拒绝走 unhandledrejection,reason 可能是 Error,也可能是字符串、对象甚至 undefined。框架层还有自己的口子:Vue 的 app.config.errorHandler、React 的 ErrorBoundary。React 边界只捕获子树在渲染、生命周期和构造函数里抛出的错误,事件处理器、setTimeout、SSR、边界自身抛的错都接不住,而且从 React 16 起,未捕获错误会卸载整棵子树。三层都接,还要做去重,否则同一个错误会被上报两三次。

第二道:跨域脚本为什么只剩一句话

浏览器有同源策略。跨域加载的脚本一旦出错,如果服务器没有授予 CORS 权限,浏览器会认为错误详情可能泄露信息,于是把 message 统一替换成 Script error.,文件名和行列号归零,error 对象为 null。这不是 bug,是安全设计。

修复要两件事同时成立:<script> 标签加 crossorigin="anonymous",CDN 响应带 Access-Control-Allow-Origin。只做一件仍然脱敏。另外,eval 和 JSONP 抛出的错误通常只能定位到 eval 或一段匿名脚本,堆栈里没有可用的源码位置,这类入口本身就该少用。

第三道:sourcemap 不是万能的

线上代码经过压缩,堆栈里只有 a.b(c) 和行列号。sourcemap 保存了压缩代码到源码的映射,但要还原成功,需要三个条件同时满足:构建产物与 release 精确对应;map 在 CI 阶段上传到监控平台,而不是随静态资源一起公开部署;堆栈里的文件名、行列号与上传的 map 完全对得上。缺一个,还原结果就可能错行甚至错文件。

还有个常见事故:把 .map 直接部署到 CDN。浏览器开发者工具确实能因此看到源码,但任何人也都能下载整份源码。正确做法是构建时用 hidden(Vite/Rollup)或 hidden-source-map(webpack),不生成 sourceMappingURL 注释,再把 map 单独上传。

第四道:没有上下文的堆栈等于没有信息

一条 TypeError: Cannot read properties of undefined 本身说明不了什么。要定位,至少需要 release、路由、session id、出错前的操作序列(面包屑)、设备与网络、关联的请求 ID。这些字段决定了你是在"修一个已知问题"还是在"猜一个故事"。

传输也有坑。页面关闭时普通 XHR 会被取消,所以要用 sendBeacon 或 fetch(..., {keepalive: true})。sendBeacon 只能 POST、不能自定义请求头,常见浏览器对单次载荷有约 64KB 的限制,超了会返回 false,需要分批和兜底。触发时机上,pagehide 和 visibilitychange 比 beforeunload 在移动端可靠得多。若页面进了往返缓存(bfcache),从 pageshow 的 persisted 状态恢复时要先清空旧队列,否则同一批错误会被重复发送。

const queue = [];
const push = (p) => queue.push(p);

addEventListener('error', (e) => {
  if (e.target && e.target !== window) {          // resource load failure
    push({ kind: 'resource', tag: e.target.tagName, url: e.target.src || e.target.href });
    return;
  }
  push({ kind: 'js', message: e.message, stack: e.error?.stack,
         file: e.filename, line: e.lineno, col: e.colno });
}, true);                                          // capture phase is required

addEventListener('unhandledrejection', (e) => {
  push({ kind: 'promise', reason: String(e.reason?.stack || e.reason) });
});

addEventListener('pagehide', () => {
  navigator.sendBeacon('/monitor', new Blob([JSON.stringify(queue)], { type: 'text/plain' }));
});

最后一步:聚合与告警

到了服务端,如果按原始 message 分组,同一个 bug 会因为变量不同被拆成上千条。指纹应该基于错误类型加归一化后的堆栈帧(去掉行列号、数字、地址),并且把 release 纳入指纹,否则新版本会被历史错误淹没。告警看影响面:受影响会话占比、新出现的指纹、发版后的基线变化,而不是原始条数。

常见考点与误区

  • 考点:挂一个 window.onerror 是不是就够了? 不够。它收不到 Promise 拒绝、资源加载失败和框架内部错误;而且 onerror 返回 true 会吞掉控制台默认输出,排查时反而更麻烦。
  • 误区:"Script error." 是浏览器 bug,加个 crossorigin 就好。 标签属性和响应头必须同时满足;只加属性、CDN 不返回 CORS 头,照样脱敏。这是同源策略在保护跨域脚本的内容。
  • 误区:有 sourcemap 就能自动还原。 map 与 release 不匹配、构建用了 eval/inline、上传时丢了文件、行列号有偏移,都会让还原失败;把 map 公开部署还会泄露源码。
  • 考点:React ErrorBoundary 能捕获所有错误吗? 不能。它只覆盖子树渲染与生命周期中的错误,事件处理器、异步回调、SSR、边界自身的错误都要靠全局兜底。
  • 误区:错误也按比例采样,省点量。 错误是长尾,采样会直接丢掉罕见但致命的 bug;该采样的是性能指标和会话回放。反过来完全不限流,又会被循环报错打爆。
  • 误区:错误数下降说明质量变好。 也可能是 SDK 被广告拦截、上报域名失效、发版后初始化失败。要同时看采集健康度:上报成功率、活跃会话数、版本覆盖率。
  • 考点:sendBeacon 的限制。 只能 POST、不能自定义请求头、约 64KB 上限,队列满时返回 false;需要 fetch keepalive 兜底并分批发送。

实践建议

  • 采集收口到一个 SDK:统一接 error 捕获、unhandledrejection、资源错误和框架钩子;SDK 自身用 try/catch 包住,上报逻辑出错不能再触发上报,避免递归风暴。同一指纹加时间窗去重,队列设上限并持久化。
  • 符号化做成流水线:CI 里开启 hidden sourcemap,上传时带 release(如 git sha)和构建号,上传后拿一条真实堆栈做还原校验。.map 不部署、上传令牌不打进前端包。
  • 上下文默认最小化:URL 去掉 query,输入内容与文本脱敏,不收集 cookie、token 和完整手机号;提供 beforeSend 让业务二次裁剪。session id 随机生成,不跨站追踪。
  • 传输走第一方域名或反向代理,降低被广告拦截的概率;sendBeacon 为主、fetch keepalive 兜底,pagehide 与 visibilitychange 双保险,接收端尽快返回 202。
  • 上线前做一次演练:canary 环境主动抛一个测试错误,确认采集、跨域、符号化、聚合、告警整条链路都通;把"采集是否健康"本身也做成监控指标。

一句话总结:前端监控的差距不在收到了多少报错,而在每条报错还剩下多少可还原的现场。

相关阅读

← 返回文章志