前端错误监控实战：onerror、unhandledrejection 和 sourcemap 定位问题

前端线上问题最麻烦的地方在于：用户看到页面白屏、按钮没反应、数据加载失败，但开发者本地很难复现。如果没有错误监控，只能靠用户截图和客服描述猜问题，定位效率会非常低。

本文用一个轻量方案，搭一条从浏览器捕获错误、整理字段、上报接口、sourcemap 还原源码位置、分派告警的闭环。它不追求一次做成大型监控平台，而是先把“线上异常能被看见、能被定位、能被跟进”这件事做稳。

摘要

前端错误监控至少要覆盖两类入口：同步运行时报错和 Promise 未处理拒绝。采集后不要把原始对象直接上报，而是整理成稳定字段，包括页面地址、错误消息、堆栈、浏览器信息、用户标识和版本号。生产环境还需要用 sourcemap 把压缩后的堆栈还原到源码行号，再进入告警和修复流程。

适合人群

适合正在维护中后台、H5 活动页、管理系统、组件库文档站的前端开发者。你需要了解基础 JavaScript、浏览器事件和接口请求。

目录

• 为什么线上错误不能只看控制台
• 从浏览器捕获错误到上报接口
• 整理一份稳定的错误字段
• 用 sourcemap 还原线上堆栈并分派告警
• 上线前检查清单

一、为什么线上错误不能只看控制台

开发环境里，控制台能直接看到报错行号；线上环境里，代码被压缩、文件名带 hash、用户设备和网络也不一样。等到用户反馈时，问题可能已经不是当前版本了。

错误监控的价值不是“收集越多越好”，而是把关键上下文保存下来：哪个页面、哪个版本、什么错误、发生了几次、影响了多少用户、是否已经有人处理。

二、从浏览器捕获错误到上报接口

最小采集链路可以分成五步：页面出现错误；浏览器事件捕获；前端整理字段；上报到接口；后台展示监控面板。

先监听同步错误和资源加载错误：

window.addEventListener("error", function (event) {
  const target = event.target;

  if (target && target !== window) {
    reportError({
      kind: "resource",
      message: target.src || target.href || "resource load failed",
      stack: "",
      filename: location.href,
      line: 0,
      column: 0,
    });
    return;
  }

  reportError({
    kind: "runtime",
    message: event.message,
    stack: event.error ? event.error.stack : "",
    filename: event.filename,
    line: event.lineno,
    column: event.colno,
  });
}, true);

再监听 Promise 未处理拒绝：

window.addEventListener("unhandledrejection", function (event) {
  const reason = event.reason || {};

  reportError({
    kind: "promise",
    message: reason.message || String(reason),
    stack: reason.stack || "",
    filename: location.href,
    line: 0,
    column: 0,
  });
});

这两个入口能覆盖大多数运行时报错。资源加载错误要使用捕获阶段监听，否则有些图片、脚本、样式加载失败不会冒泡到普通监听器。

三、整理一份稳定的错误字段

上报前建议统一字段，不要把不同浏览器的原始对象直接丢给后端。一个基础字段可以这样设计：

function buildErrorPayload(raw) {
  return {
    kind: raw.kind,
    message: raw.message || "",
    stack: raw.stack || "",
    filename: raw.filename || location.href,
    line: raw.line || 0,
    column: raw.column || 0,
    url: location.href,
    title: document.title,
    userAgent: navigator.userAgent,
    release: window.__APP_RELEASE__ || "unknown",
    time: new Date().toISOString(),
  };
}

上报接口也要做降级处理。监控不能影响页面主流程，所以推荐用 navigator.sendBeacon，失败时再退回普通请求。

function reportError(raw) {
  const payload = buildErrorPayload(raw);
  const body = JSON.stringify(payload);
  const url = "/api/frontend-errors";

  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
    return;
  }

  fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body,
    keepalive: true,
  }).catch(function () {
    // 监控上报失败时静默处理，避免影响用户操作
  });
}

字段里最重要的是 release。没有版本号，后端很难判断同一个错误到底来自哪个构建产物，也很难匹配对应的 sourcemap 文件。

四、用 sourcemap 还原线上堆栈并分派告警

生产环境的堆栈常常长这样：文件名是 hash，行列号也对应压缩后的 bundle。没有 sourcemap，开发者只能在一大坨压缩代码里找问题。

建议构建时保留 sourcemap，但不要把它公开给所有用户下载。更稳的做法是：构建产物发布到静态资源服务器，sourcemap 单独上传到监控后台或内部对象存储。

// vite.config.js 示例
export default {
  build: {
    sourcemap: true,
  },
};

后端收到错误后，可以按 release 和文件名找到对应 sourcemap，再把压缩堆栈还原成源码路径、函数名和行列号。还原完成后，就可以按路由、目录、组件负责人做告警分派。

五、错误去重和告警阈值

如果每次错误都发一条告警，开发者很快就会麻木。更好的方式是按指纹聚合。指纹通常由错误类型、消息、源码位置和版本号组成。

function buildFingerprint(payload) {
  return [
    payload.kind,
    payload.message,
    payload.filename,
    payload.line,
    payload.column,
    payload.release,
  ].join("|");
}

告警规则可以从简单开始：

• 同一指纹 10 分钟内超过 20 次，通知前端值班同学。
• 同一指纹影响用户数超过 5 人，创建修复任务。
• 白屏相关错误直接提高优先级。
• 新版本发布后 30 分钟内出现高频错误，提示回滚风险。

常见问题

1. sourcemap 要不要放到公网？

不建议。sourcemap 会暴露源码结构，最好上传到内部监控系统，由后端在还原堆栈时使用。

2. 监控上报失败要不要提示用户？

一般不需要。监控是辅助链路，上报失败不能影响用户继续操作。业务失败要按业务规则提示，监控失败保持静默即可。

3. 只接入第三方监控还需要自定义字段吗？

需要。第三方工具能采集通用错误，但业务维度如用户等级、租户 ID、版本号、页面模块、实验分组，仍然建议自己补充。

上线前检查清单

• 是否同时监听了 error 和 unhandledrejection。
• 资源加载错误是否使用捕获阶段监听。
• 上报字段是否包含 release、页面地址、错误消息和堆栈。
• sourcemap 是否上传到内部系统，而不是直接公开。
• 是否按错误指纹做聚合，避免告警刷屏。
• 是否能从告警跳到责任人、源码位置和修复任务。

总结

前端错误监控要解决的是“线上问题可见、可定位、可跟进”。从浏览器事件采集开始，整理稳定字段，上报到后台，再用 sourcemap 还原源码位置，最后按指纹聚合并分派告警。先把这条链路跑通，再逐步补充性能指标、用户行为轨迹和白屏检测，整个线上排查体验会稳很多。