2023 年冬天,运营转来一张用户截图:整页白屏,只有顶部的导航还在。截图来自一台安卓千元机,用的某国产浏览器。我们打开监控后台,搜这个时间段的错误,只有三条 Script error.,没有文件名、没有行号、没有堆栈,也没有用户标识。等于什么都没说。

最后查了三天。真正的原因是某个第三方 SDK 在这个浏览器的 WebView 内核上初始化失败,抛错之后阻断了后续模块执行。这类问题在实验室里永远复现不了,只能靠真实用户的现场数据。而我们当时的「监控」只是一个接了 SDK 的后台,没人维护,没人看,也没人知道它大部分时候是瞎的。

这篇讲前端监控的三条通道——错误、性能、埋点——各自在什么位置失效,以及怎么用最低成本让它们变得可信。性能通道上一篇已经讲过,这里只讲它和错误通道的交界。重点放在最容易做错、也最影响排查效率的地方。

先承认一件事:大多数监控数据是坏的

「接了监控」和「监控能用」是两件事。判断能不能用,问四个问题:

能不能定位到具体代码?如果堆栈只有 Script error. 或者压缩后的 a.b is not a function,等于没有。

能不能定位到具体用户和环境?机型、系统、浏览器、网络、版本、路由、操作路径,缺一样都可能在排查时卡住。

能不能区分「一个 bug」和「一万次报错」?没有聚合,一个死循环就能把后台刷爆,把真正的信号埋掉。

数据里的用户信息合规吗?URL 里带 token、错误信息里带手机号,这类事故在国内是有真实处罚案例的。

监控的第一原则是「能复现」。任何一条上报,如果拿不到版本号、路由、设备和操作序列,它的排查价值就只剩一半。字段设计比 SDK 选型重要得多。

那次选型:三条通道分开做

我们当时的约束很具体:200 万月活的 C 端产品,加三个内部后台;数据不能出境;团队没有专职的监控开发;已有的埋点平台是公司统一的数据团队维护的。

约束实际情况对方案的影响
数据合规用户数据不能出境,敏感字段要脱敏排除纯海外 SaaS;上报前必须过滤
流量200 万月活,错误高峰时每分钟数千条必须有采样、聚合和限流
团队无专职监控开发,前端共 20 人能买就买,自建只做必须自建的部分
埋点公司有统一数据平台和 schema 规范埋点必须走既有通道,不能自己另起一套
多端Web、两个 Hybrid WebView、一个微信小程序SDK 要能覆盖多端,或接受部分端降级

方案对比下来,结论是「不要一个 SDK 干所有事」。这个结论反直觉,但很实用。

A. 一个全家桶 SDK 包办

错误、性能、埋点都用一个厂商的 SDK。接入快,看板统一。代价是每项都不够深:埋点口径要迁就它的模型,性能采样不可控,出问题时只能等厂商排期。

B. 全部自建

完全可控,字段想加就加。代价是采集、传输、存储、聚合、告警、看板全要自己做,20 人的前端团队至少搭进去一个人力,而且做出来的质量大概率不如成熟产品。

C. 错误用成熟方案,性能用轻量自建,埋点走数据平台

错误交给 Sentry(自托管,数据在境内),性能用上一篇那套 web-vitals 加 sendBeacon,埋点接公司统一 schema。三条通道各自最优,代价是要维护三套接入和三个看板。

D. 只用日志平台,前端错误写进后端日志

实现最省事,但前端错误混在服务端日志里,没有 sourcemap、没有设备信息、没有用户维度,排查效率极低。只适合极小规模的内部系统。

我们选了 C。核心理由是「错误排查需要专业工具,埋点分析需要统一口径,性能采集需要自己控制采样」。三者耦合在一个 SDK 里,任何一项想改都会牵动另外两项。分开之后,每项都可以独立替换,代价是多维护两套接入代码。

// 最小可用的错误采集骨架(生产环境还需要采样与限流)
window.addEventListener("error", (event) => {
  // 资源加载错误没有 error 对象,要单独判断
  const target = event.target;
  if (target && (target.tagName === "SCRIPT" || target.tagName === "LINK")) {
    report({ type: "resource", url: target.src || target.href });
    return;
  }
  report({
    type: "js",
    message: event.message,
    filename: event.filename,
    line: event.lineno,
    column: event.colno,
    stack: event.error && event.error.stack
  });
});

window.addEventListener("unhandledrejection", (event) => {
  const reason = event.reason;
  report({
    type: "promise",
    message: reason && reason.message ? reason.message : String(reason),
    stack: reason && reason.stack
  });
});

这段代码只能保证「能收到」,离「能查」还差很远。下面逐项补。

跨域脚本:为什么你只能看到 Script error.

浏览器有一条安全规则:跨域加载的脚本发生错误时,如果不满足 CORS 条件,错误详情会被抹掉,只留一句 Script error.。目的是防止恶意站点通过错误信息探测其他域的内容。这条规则对所有 CDN 上的脚本生效,而绝大多数项目的 JS 都在 CDN 上。

解决办法是两件事同时做:脚本标签加 crossorigin="anonymous",CDN 返回 Access-Control-Allow-Origin 头。只做一件没有用——加了属性但服务端不给头,脚本会直接加载失败;给了头但没加属性,浏览器仍然抹掉详情。

Vite 和 webpack 都有配置项可以批量给产物加这个属性,但要注意:一旦加上,CDN 的 CORS 配置就成了硬依赖。我们有一次换了 CDN 服务商,忘了配这个头,结果全站脚本加载失败,白屏了十几分钟。上线前在预发环境验证一遍,成本很低。

sourcemap:上传了不等于能看到

有了堆栈还不够,压缩后的代码是 a.b(c,d),得靠 sourcemap 还原。这里有三条容易踩的坑。

第一,sourcemap 不能公开。公开的 sourcemap 等于把源码送给所有人,包括内部接口路径和注释。正确做法是构建时生成 hidden-source-map,上传到监控平台,部署目录里不留 .map 文件。

第二,版本号必须对得上。监控平台靠 release 版本或 sourcemap 里的文件名匹配。我们有过一次「上传成功但看不到源码」,查了半天是构建时注入的 release 和上传时用的 release 差了一个后缀。现在这条写进了发布脚本,构建产物和上传用同一个变量。

第三,sourcemap 里的源码路径要可读。打包工具默认会写相对路径或者带哈希的路径,还原出来的堆栈全是 ../src/xxxx.js。配置 sourcemapPathOverrides 或者构建时保留原始路径,能省掉大量猜测。

sourcemap 本身可能包含源码内容(sourcesContent)。如果代码里有硬编码的测试密钥、内部域名、员工信息,上传前要么关掉 sourcesContent,要么确保存储端访问受控。我们做过一次扫描,在一个老项目的 sourcemap 里找到了三年前的内网地址。

聚合:别让一万条报错淹掉一个 bug

错误上报是「按次」的,排查需要的是「按问题」。两者之间要靠聚合。聚合的常见做法是用一个 fingerprint:错误类型 + 错误信息模板 + 堆栈关键帧。

坑在于「错误信息模板」。如果直接把原始 message 当指纹,Cannot read property 'name' of undefined 和 Cannot read property 'id' of undefined 会被拆成两个问题,实际上它们是同一个 bug。更糟的是消息里带用户 ID、时间戳、随机数,每一条都是新问题。

我们的规则是把 message 里的数字、UUID、URL、引号内容全部替换成占位符,再取堆栈的前三帧做哈希。这样同一个代码位置的不同数据会聚在一起,不同代码位置也不会被误合并。

另一层是「错误风暴」保护。一个在 requestAnimationFrame 里抛错的组件,一秒能报六十次;一个坏掉的接口轮询,能让整个页面每分钟报几百条。如果 SDK 没有客户端限流,后台会被一个 bug 刷爆,配额和告警全部失效。我们在采集端做了三件事:同类错误每分钟最多上报 5 条;单页面会话总上报量上限 50 条;SDK 自身的错误绝不再上报,避免递归。

上下文:让每一条错误都能被复现

一条错误如果只有 message,排查价值很低。我们会附上这些字段,按重要性排序:

版本与路由release 版本号、当前路由、来源页面。用于判断是不是新版本引入。
设备与环境机型档位、系统版本、浏览器内核、屏幕尺寸、网络类型。用于判断是不是特定环境。
用户标识匿名化的用户 ID,用于把同一用户的多次错误串起来。绝不带手机号、身份证。
操作面包屑最近 20 次点击、路由跳转、接口请求(脱敏后)。用于还原操作路径。
状态快照关键 store 的摘要、登录态、灰度分组。用于判断是不是特定状态触发。

面包屑是最有用也最危险的一项。有用是因为「用户点了什么才触发」几乎只能靠它还原;危险是因为它很容易顺手把敏感信息带上去:URL 里的 token、请求体里的手机号、表单里的地址。我们的做法是在采集入口统一过一遍脱敏规则,而不是指望每个上报点自己记得。

埋点:和错误监控完全不同的东西

埋点经常被和监控混在一起说,但它们的目标相反:监控关心「异常」,埋点关心「正常行为的分布」。埋点做坏的方式也不一样。

口径漂移。同一个「下单成功」事件,A 团队在点击时上报,B 团队在接口返回后上报,C 团队在页面跳转时上报。三个数字永远对不上,开会先花半小时对齐口径。

重复上报。组件复用了,埋点写在组件内部,一个页面出现三次就报三次。或者路由切换时监听没解绑,越用越多。

丢事件。在 beforeunload 里发普通 XHR,页面一关请求就被取消。跳转型操作(点击后立刻 navigate)几乎必丢。

解决办法是把埋点当成「有 schema 的数据上报」,而不是随手一个 track()。事件名、字段、触发时机、去重键写在 schema 里,由数据团队评审;SDK 层统一处理去重、补发、页面卸载时的 sendBeacon。

还有一层是「看板治理」。我们最初做监控看板,恨不得把所有指标都放上去,结果开了三个月就没人点。后来收成三块:今天有没有新出现的错误、哪个版本的错误率在涨、核心流程的成功率有没有掉。每块只放三个数,点进去才看细节。看板的作用是让人每天愿意扫一眼,不是做数据大全。

告警也要有归属。一条告警如果不知道该谁处理,它最终的命运一定是被静音。我们给每类错误标了负责团队,告警直接进对应的群;超过两天没人认领的,自动升级到技术负责人。这个机制比调阈值更有效,因为大部分「告警没人看」不是阈值问题,是责任问题。

真实踩的坑

下面这张表是我们这两年修过的典型问题,基本覆盖了三条通道的主要失效模式。

现象真实原因第一步查什么
错误只有一行 Script error.跨域脚本没有 CORS,浏览器抹掉了详情看 script 标签有没有 crossorigin,CDN 有没有返回 ACAO 头
堆栈全是压缩后的短变量名sourcemap 没上传,或 release 版本不匹配比对构建产物、上传记录与错误里的 release 字段
同一个 bug 在后台显示几百条fingerprint 用了原始 message,数据部分各不相同看分组规则,检查 message 里的变量是否被归一化
错误量突然暴涨,用户却无感采集循环触发,或 SDK 自身报错递归上报看错误来源与时间分布,检查是不是同一个堆栈
上报数据里出现手机号、tokenURL 和面包屑没脱敏抽样看原始上报体,搜关键词与正则
埋点数和后端数据对不上触发时机不一致、重复上报或丢事件抽一个事件,对比客户端、接口、服务端日志三条链路
用户报错但后台查不到采样把该用户漏掉,或上报被广告拦截器拦了看采样率与拦截器命中;确认关键错误是否全量上报

最后一行值得展开:广告拦截器、隐私浏览模式、企业网络都会拦上报请求,拦截率在有些产品上能到 10%。这意味着「后台没有错误」不等于「没有错误」。关键路径的兜底不能只依赖监控,比如支付失败、白屏,要有前端自己的降级逻辑。

边界与代价:监控什么时候变成负担

日活几千的小产品,别自建。用现成的免费额度或者轻量方案,把精力放在功能上。自建的采集、存储、看板,维护成本远高于它带来的收益。

采样率不是越低越省钱。错误采样要区分「普通错误」和「致命错误」:普通错误可以 10%,白屏、支付失败、核心流程中断这类必须全量。性能指标可以按会话采样,埋点通常要全量,因为分析依赖分布。

告警阈值设太紧,等于没有告警。我们有过一周收到 40 条告警,最后没人看。后来改成「同类错误 5 分钟内超过 20 次才告警」,并且按影响用户数排序,才重新有用。

隐私边界要在采集入口就守住。路径参数里的手机号、请求体里的地址、表单里的身份证号,都可能被面包屑顺手带上。靠「上报的人记得脱敏」一定守不住,必须在 SDK 里统一过滤,并且保留一份可审计的规则清单。我们每季度抽查一次原始上报,发现过两个漏网的字段,都是新接入的页面自己加的。

监控不能替代测试。它只能告诉你「已经出事了」,不能保证「不出事」。一个没有测试的团队接再多监控,也只是把事故发现时间从用户投诉提前到告警,修复能力不会变。

今天就能动手的五件事

一、制造一个错误。在控制台执行 setTimeout(() => { throw new Error("test") }),看后台有没有收到、字段全不全、多久出现。这一步能暴露一半的接入问题。

二、检查跨域脚本。打开页面源码,看 script 标签有没有 crossorigin,再用 curl 看一眼 CDN 的响应头有没有 Access-Control-Allow-Origin。两件都满足,才可能拿到真实堆栈。

三、还原一次压缩堆栈。从后台随便挑一条错误,用 sourcemap 还原,看能不能定位到具体文件和行。定不到,就说明上传链路有问题,先修这个再谈别的。

四、加三个上下文字段。版本号、路由、设备档位,先加上,观察一周排查效率的变化。这三个字段的成本几乎为零,收益最直接。

五、做一次错误风暴演练。写一个每秒抛错十次的循环,跑一分钟,看后台是否被刷爆、告警是否失灵。演练过的系统,真出事时才不会手忙脚乱。

小结

前端监控的价值不在「采了多少数据」,而在「一条数据能不能支撑一次定位」。跨域、sourcemap、聚合、上下文、脱敏,这五项每一项缺失,都会让数据从「线索」退化成「噪音」。

监控做好之后,我们终于能看清问题集中在哪些页面。但紧接着遇到另一个问题:这些页面分散在三个团队,代码在一个巨大的单体仓库里,改一处要跑四十分钟测试,谁也说不清边界在哪。下一篇讲大型前端架构,就是从这个具体困境开始。