写了一套前端错误监控系统后，才发现最难的不是捕获，是指纹算法怎么去重才不误判

线上跑了三个月的错误监控系统，某天凌晨突然告警：同一个错误 ID 在一个小时内触发了 1200 次。我爬起来翻日志，发现这 1200 次报错里，真正需要关注的其实只有 3 种不同的错误，剩下全是同一段 try-catch 里抛出的异常在不同浏览器、不同版本下产生的堆栈变体。那一刻我才意识到，错误去重的指纹算法如果不够精准，监控系统就不是帮你发现问题，而是用噪音把你淹没。

错误监控的完整链路到底长什么样

一个生产可用的前端错误监控系统，链路远比想象中长。很多人以为核心难点在捕获，实际上捕获只是入口，真正的工程化挑战在后续的聚合、去重和告警策略上。

先说捕获层。前端需要覆盖四类错误：JS 运行时错误（window.onerror）、Promise 未捕获拒绝（unhandledrejection）、资源加载错误（error 事件捕获阶段）、以及框架层面的错误（React 的 ErrorBoundary、Vue 的 errorHandler）。关键点有两个：一是 window.onerror 拿不到跨域脚本的完整堆栈，必须在 script 标签上加 crossorigin="anonymous" 并且服务端返回 Access-Control-Allow-Origin 头；二是 ErrorBoundary 捕获的组件渲染错误，React 17 之后不会把错误继续抛到 window.onerror，必须手动上报。

捕获到的原始数据至少要包含这些字段：错误消息（message）、完整堆栈（stack）、页面 URL、发生时间戳、用户标识、浏览器 UA、以及一个额外的元数据字段供业务方自定义。我在 SDK 里设计了一个 beforeSend 钩子，允许使用方在上报前裁剪敏感信息或追加业务上下文，比如当前登录用户的 ID、所在路由路径。这对后续定位问题至关重要。

数据采集后进入传输层。这里最容易踩的坑是：错误爆发时上报请求会急剧增加，直接把带宽打满。我们的做法是用一个内存队列缓冲，每 2 秒批量发送一次，单次最多 50 条，超出则按优先级丢弃——unhandledrejection 优先级最高，其次是 JS 运行时错误，资源加载错误最低。队列满了怎么办？不是简单地丢弃新数据，而是保留最新的、丢弃最旧的。因为错误刚发生时，最新的堆栈信息往往最能反映当前状态。

接下来是存储与聚合。原始错误日志写入 ClickHouse，按时间分区，保留周期 90 天。但用户不会去看原始日志，他们需要一个聚合视图：同一个错误出现了多少次、影响了多少用户、发生在哪些页面、趋势是上升还是下降。这个聚合视图的输入，就是去重后的错误分组，而分组的依据，正是指纹。

指纹算法的核心矛盾：太松了误判，太紧了漏判

指纹的作用是把"本质相同"的错误归为一类。问题在于，什么算"本质相同"？如果只按 message 字段做 md5，那 Cannot read property 'name' of undefined 和 Cannot read property 'age' of undefined 会被算成两个不同的错误，但实际上它们很可能是同一段代码在不同调用路径下暴露的问题，应该合并。反过来，如果只取堆栈的前几帧，那不同浏览器对同一段代码生成的堆栈可能有细微差异——Chrome 的堆栈格式和 Safari 就不一样，Firefox 还会在函数名后面加上列号——这些差异会导致同一个错误被拆成多个分组。

我们踩过的坑很具体。第一个版本直接用 message + stack 的 MD5 作为指纹。结果发现，堆栈里包含了完整的 URL 查询参数，同一个页面报的错，因为每次请求带了不同的 timestamp 参数，指纹全都不一样。第二个版本改成只取 message 加上堆栈中每个栈帧的文件名和行号，忽略查询参数。但紧接着又发现，生产环境的代码是经过 webpack 打包和压缩的，每次发版后模块 ID 可能变化，导致同一个源文件在不同版本里对应不同的模块 ID，堆栈中的文件名变了，指纹又变了。

这就引出了指纹算法设计的核心权衡：你需要在"同一类错误"的定义上做出工程决策。我们的最终方案分三步走。

第一步，堆栈标准化。拿到原始堆栈后，先做三件事：去除每行堆栈中 URL 的查询参数和 hash；将压缩后的文件名通过 source map 还原为源文件名（这一步在服务端异步完成，因为 source map 文件通常很大，不适合在客户端处理）；对还原后的堆栈帧做归一化，只保留函数名、源文件名、行号、列号四个字段。这里有一个细节：如果 source map 还原失败（比如文件过期或丢失），就降级使用压缩后的文件名，但要剔除掉 webpack 的模块 ID 那部分——我们通过正则匹配 webpack:///./src/ 这种模式来提取真实路径。

第二步，生成指纹的输入字符串。不是把整个标准化后的堆栈都拿去 hash，而是只取堆栈的前 3 帧。理由是：同一个错误在不同浏览器或不同调用路径下，堆栈的底部分支可能完全不同，但抛出错误的直接位置和它的前两层调用者通常是一致的。取 3 帧是一个经验值——取 1 帧太激进，容易把不同错误合并；取 5 帧太保守，容易把同一错误拆分。我们在实际数据上做过对比：取 3 帧时，分组数量比取 1 帧多 12%，比取 5 帧少 8%，人工抽检了 200 个分组，误判率（应该合并但拆开了）在 3% 以内，漏判率（不应该合并但合并了）在 2% 以内。

第三步，对输入字符串做 SHA256。选 SHA256 而不是 MD5，不是出于安全考虑，而是因为 SHA256 的碰撞概率更低，在百万级别错误分组下几乎不可能出现两个不同错误产生相同指纹。MD5 在理论上有碰撞风险，虽然实际概率极低，但既然计算成本差异可以忽略，没必要留这个隐患。

最终的指纹生成逻辑用伪代码表示如下：

function generateFingerprint(error) {
  // 1. 标准化 message：去掉动态数字、UUID 等
  const normalizedMessage = normalizeMessage(error.message);
  
  // 2. 解析并标准化堆栈
  const frames = parseStackTrace(error.stack);
  const normalizedFrames = frames
    .map(normalizeFrame)      // 去除查询参数、还原源文件
    .slice(0, 3);             // 只取前 3 帧
  
  // 3. 拼接指纹输入
  const fingerprintInput = [
    normalizedMessage,
    ...normalizedFrames.map(f => `${f.functionName}@${f.fileName}:${f.line}:${f.column}`)
  ].join('||');
  
  // 4. SHA256
  return sha256(fingerprintInput);
}

message 的归一化比堆栈更棘手

堆栈标准化固然麻烦，但 message 的归一化才是真正的暗坑。错误消息里经常嵌入了运行时变量，比如 Cannot read property '12345' of undefined、Invalid user ID: abc-def-ghi、Timeout: 5000ms exceeded。这些动态值如果不处理，每一个不同的变量值都会产生一个独立的指纹。

我们的做法是维护一个归一化规则集合，按优先级依次应用。规则分三类：第一类是通用模式替换，用正则将数字、UUID、hex 字符串替换为占位符 <NUM>、<UUID>、<HEX>；第二类是框架特定的消息模式，比如 React 的错误消息 Minified React error #XXX 中的错误码是固定的，我们维护了一个 React 错误码到完整消息的映射表，还原后再归一化；第三类是业务方自定义的归一化规则，通过 SDK 的配置项传入。

这里有一个取舍：归一化做得越激进，分组越少，但不同错误的边界越模糊。我们的原则是，归一化只处理"明显是动态值"的部分，保留错误消息的结构信息。举个例子，Cannot read property 'x' of null 和 Cannot read property 'y' of undefined 在我们的规则下会被合并为 Cannot read property '<VAR>' of <TYPE>，因为结构相同。但 Cannot read property 'x' of null 和 x is not defined 不会被合并，因为消息的结构完全不同。

这条规则上线后，错误分组数量从之前的 8,300 个下降到了 1,200 个左右，运维人员终于能从告警列表里快速定位到真正需要处理的问题了。

版本迭代与 source map 的管理

指纹算法还跟一个基础设施问题深度绑定：source map 的管理。如果 source map 丢了或版本对不上，堆栈还原失败，指纹就会基于压缩后的代码生成，这意味着每次发版后同一个错误的指纹可能变化，之前静默处理掉的错误会重新出现。

我们的 source map 管理方案是：CI/CD 构建完成后，将 source map 文件上传到对象存储，路径为 /{project}/{version}/{filename}.map。SDK 上报错误时附带当前部署的版本号（在构建时注入环境变量），服务端根据版本号拉取对应的 source map 进行还原。source map 文件设置 30 天的生命周期，超过 30 天的版本自动过期删除——这个时间窗口足够覆盖绝大部分错误的分析需求，同时控制了存储成本。

还有一个边缘情况：用户浏览器缓存了旧版本的 JS 文件，但服务端已经更新了新版本的 source map。这时候上报的堆栈行号可能对不上新 source map，还原会失败。我们的处理是：还原失败时，用压缩后的堆栈生成指纹，但在错误详情页标记"source map 还原失败"，提示可能是旧版本缓存导致。这个标记比错误本身更有价值，因为它暴露了一个部署层面的问题。

常见问题

为什么不用 error.message 直接当指纹？

因为 message 里经常包含动态变量，比如用户 ID、时间戳、数组下标。同一个逻辑错误在不同调用场景下产生的 message 字符串不同，直接用会拆出大量无效分组。必须做归一化处理，把动态部分替换为占位符。

取堆栈前 3 帧够吗？不同错误的根因可能在更深的调用栈里。

3 帧是一个工程权衡。取更多帧确实能区分更多错误，但同时也会因为浏览器差异、异步调用路径不同而把同一个错误拆开。我们在实际数据上验证过，取 3 帧时误判率和漏判率都在可接受范围内。如果你面对的场景是深层递归或高度抽象的框架（比如 Redux-Saga 的 generator 调用栈），可以调整到 5 帧，但要相应调整告警阈值，避免同一个错误被拆成多个告警。

source map 上传到公共服务会不会有安全风险？

source map 包含源码路径和部分代码片段，确实有泄露风险。我们的做法是：对象存储设置私有读写，服务端通过内网 API 拉取，不对公网暴露。如果公司安全策略更严格，可以在 CI 阶段对 source map 做加密，服务端解密后再使用。另外，生产环境的 source map 不建议通过 devtool: 'source-map' 直接暴露给浏览器，应该只在 CI 阶段生成并上传到内部存储，线上用 devtool: 'hidden-source-map'。