前端异常捕获与统一格式化：从 console.log(error) 到服务端上报

🧑 博主简介：CSDN博客专家，「历代文学网」（公益文学网，PC端可以访问：https://lidaiwenxue.com/#/?__c=1000，移动端可关注公众号 “ 心海云图 ” 微信小程序搜索“历代文学”）总架构师，首席架构师，也是联合创始人！16年工作经验，精通Java编程，高并发设计，分布式系统架构设计，Springboot和微服务，熟悉Linux，ESXI虚拟化以及云原生Docker和K8s，热衷于探索科技的边界，并将理论知识转化为实际应用。保持对新技术的好奇心，乐于分享所学，希望通过我的实践经历和见解，启发他人的创新思维。在这里，我希望能与志同道合的朋友交流探讨，共同进步，一起在技术的世界里不断学习成长。 🤝商务合作：请搜索或扫码关注微信公众号 “ 心海云图 ”

前端异常捕获与统一格式化：从 console.log(error) 到服务端上报

引言

在前端开发中，异常监控是保证应用稳定性的重要一环。当用户遇到页面白屏、功能不可用等问题时，如果能及时收集到详细的错误信息（包括堆栈、行列号、浏览器环境等），就能快速定位并修复 bug。浏览器提供了 window.onerror 和 unhandledrejection 两个全局事件，分别用于捕获未处理的 JavaScript 异常和未捕获的 Promise 拒绝。然而，不同浏览器对这些事件的参数支持存在差异，错误对象的格式也各不相同，如何编写一个兼容所有浏览器、并能像 console.log(error) 那样输出完整堆栈的格式化函数，是搭建前端监控系统的第一步。

本文将带你深入理解 console.log(error) 的底层实现，并给出一个通用的错误格式化方案，最后演示如何将格式化后的异常信息上报到后端。

为什么需要统一格式化？

当你在控制台直接执行 console.log(new Error('something wrong')) 时，浏览器会打印出类似这样的信息：

Error: something wrong
at <anonymous>:1:13
at …

但如果使用 window.onerror 捕获，你拿到的参数可能只有消息、脚本 URL、行号、列号和一个可选的 error 对象。这些参数组合起来未必能还原出完整的堆栈。此外，unhandledrejection 的 reason 可能是任意类型（字符串、对象、Error 实例等），如何安全地提取信息并拼接成可读的字符串，也需要仔细处理。

一个优秀的异常上报方案应该做到：

• 完整性：尽可能包含错误名称、消息、调用堆栈、发生位置（文件、行号、列号）。
• 兼容性：支持所有主流浏览器（包括 IE9+）。
• 健壮性：处理循环引用、非 Error 对象等特殊情况，避免二次异常。
• 一致性：最终上报的字符串格式统一，便于后端解析或搜索。

console.log(error) 的底层原理

在深入实现之前，我们先了解一下浏览器是如何打印错误对象的。以 Chrome 的 V8 引擎为例：

因此，要获得与 console.log 相同的输出，我们只需在全局事件中尽量获取到 error.stack 即可。当无法获取 stack 时，再根据事件参数手动拼接位置信息。

统一错误格式化函数

下面是一个健壮的 formatError 函数，它接受任意类型的错误值以及可选的 URL、行号、列号，返回格式化的错误字符串。

/**
* 将任意错误值格式化为包含堆栈信息的字符串
* @param {*} error – 错误对象或任意值
* @param {string} fallbackMessage – 当无法获取有效信息时的备选消息
* @param {string} [url] – 发生错误的脚本URL（从onerror获取）
* @param {number} [line] – 行号（从onerror获取）
* @param {number} [col] – 列号（从onerror获取）
* @returns {string} 格式化后的错误字符串
*/
function formatError(error, fallbackMessage, url, line, col) {
let result = '';

// 情况1：error 是对象类型，尝试提取 stack 或 message
if (error && typeof error === 'object') {
// 优先使用 stack（包含完整的调用堆栈）
if (typeof error.stack === 'string') {
result = error.stack;
}
// 其次使用标准 error 属性（name 和 message）
else if (typeof error.message === 'string') {
const name = error.name || 'Error';
result = `${name}: ${error.message}`;
}
// 否则尝试 JSON 序列化（避免循环引用）
else {
try {
result = JSON.stringify(error, null, 2);
} catch (e) {
// 序列化失败（如循环引用），使用默认字符串转换
result = String(error);
}
}
} else {
// 原始类型直接转为字符串
result = String(error);
}

// 情况2：结果中不包含行列信息（如只拿到 message），但通过 onerror 获得了具体位置
// 简单判断堆栈中是否已有类似 ":数字" 的行号标记
const hasLineInfo = /:\\d+/.test(result);
if (!hasLineInfo && url && line) {
const location = `${url}:${line}${col ? ':' + col : ''}`;
result = result ? `${result} at ${location}` : `Error at ${location}`;
}

// 情况3：仍然没有有效内容，使用 fallbackMessage
if (!result && fallbackMessage) {
result = fallbackMessage;
}

return result;
}

关键点说明

• 优先使用 error.stack：只要错误对象有 stack 属性，就直接使用它，因为 stack 已经包含了最完整的调用链和位置信息。
• 降级使用 name 和 message：如果对象是 Error 实例但 stack 可能被篡改或不存在，则拼接 name: message。
• JSON 序列化兜底：对于普通对象（如 { code: 500, msg: 'fail' }），尝试用 JSON.stringify 展示其结构，并捕获循环引用异常。
• 附加行列号：当最终字符串中没有明显的数字位置（如 :10）且外部提供了 URL 和行号时，将位置信息附加到末尾。这可以弥补某些场景下 error.stack 缺失行列的不足。
• fallbackMessage 参数：当 error 为 undefined 或空值时，可以传入默认消息，例如 'Unhandled Rejection'。

全局监听器：window.onerror 和 unhandledrejection

有了格式化函数，我们就可以在全局事件中调用它，并将结果上报。

window.onerror

window.onerror = function (message, source, lineno, colno, error) {
const errorStr = formatError(error, message, source, lineno, colno);

// 上报错误（示例：使用 sendToServer 函数）
sendToServer({
type: 'onerror',
message: message,
stack: errorStr,
url: source,
line: lineno,
column: colno,
userAgent: navigator.userAgent,
timestamp: Date.now()
});

// 返回 true 可以阻止浏览器默认处理（如控制台打印错误）
// return true;
};

注意：旧版 IE（<=10）不会传递 error 参数，此时 error 为 undefined，我们的 formatError 会使用 fallbackMessage（即 message）和行列号来构造字符串。

unhandledrejection

window.addEventListener('unhandledrejection', function (event) {
const reason = event.reason;
const errorStr = formatError(reason, 'Unhandled Rejection');

sendToServer({
type: 'unhandledrejection',
reason: errorStr,
userAgent: navigator.userAgent,
timestamp: Date.now()
});

// 可选：阻止默认行为（某些浏览器会打印错误）
event.preventDefault();
});

event.reason 可以是任何类型，我们的 formatError 已经做了充分处理。

上报函数实现

最简单的上报可以通过 navigator.sendBeacon 或 fetch 发送到后端接口。为了不影响用户体验，建议使用 sendBeacon，它会在页面卸载时也能确保请求发出。

function sendToServer(data) {
// 避免频繁上报（例如使用采样率）
if (Math.random() > 0.1) return; // 10% 采样

const url = 'https://your-monitor-server.com/api/error';
const body = JSON.stringify(data);

if (navigator.sendBeacon) {
navigator.sendBeacon(url, body);
} else {
fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: body,
keepalive: true // 类似 sendBeacon 的行为
}).catch(() => {}); // 忽略 fetch 失败
}
}

兼容性深度解析

不同浏览器的 window.onerror 参数

我们的 formatError 能够适应以上所有情况：当 error 不存在时，利用 message、source、lineno 构造一个简化版本。

堆栈格式差异

不同浏览器生成的 error.stack 格式略有不同，例如：

• Chrome: Error: message\\n at function (file:line:column)
• Firefox: Error: message\\n function@file:line:column
• Safari: Error: message\\n function@file:line:column
• IE: Error: message\\n at function (file:line:column)

这些格式差异通常不影响可读性，我们的格式化函数直接保留原始 stack，不进行解析和重组，以保证信息不丢失。

完整示例代码

将上述片段整合，得到一个完整的监控模块：

// error-monitor.js
(function() {
'use strict';

function formatError(error, fallbackMessage, url, line, col) {
let result = '';
if (error && typeof error === 'object') {
if (typeof error.stack === 'string') {
result = error.stack;
} else if (typeof error.message === 'string') {
const name = error.name || 'Error';
result = `${name}: ${error.message}`;
} else {
try {
result = JSON.stringify(error, null, 2);
} catch (e) {
result = String(error);
}
}
} else {
result = String(error);
}

const hasLineInfo = /:\\d+/.test(result);
if (!hasLineInfo && url && line) {
const location = `${url}:${line}${col ? ':' + col : ''}`;
result = result ? `${result} at ${location}` : `Error at ${location}`;
}

if (!result && fallbackMessage) {
result = fallbackMessage;
}

return result;
}

function sendToServer(data) {
// 采样：仅上报 10% 的错误，可根据需要调整
if (Math.random() > 0.1) return;

const url = 'https://your-monitor-server.com/api/error';
const body = JSON.stringify({
…data,
userAgent: navigator.userAgent,
timestamp: Date.now(),
page: window.location.href
});

if (navigator.sendBeacon) {
navigator.sendBeacon(url, body);
} else {
fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: body,
keepalive: true
}).catch(() => {});
}
}

window.onerror = function (message, source, lineno, colno, error) {
const errorStr = formatError(error, message, source, lineno, colno);
sendToServer({
type: 'onerror',
rawMessage: message,
stack: errorStr,
url: source,
line: lineno,
column: colno
});
};

window.addEventListener('unhandledrejection', function (event) {
const reason = event.reason;
const errorStr = formatError(reason, 'Unhandled Rejection');
sendToServer({
type: 'unhandledrejection',
stack: errorStr
});
event.preventDefault();
});
})();

进阶考虑

1. 去重与聚合

大量相同错误重复上报会浪费资源。可以在前端缓存最近上报的错误指纹（如 error.stack 的哈希），短时间内相同的错误不再发送。

2. 错误采样

对于高流量的应用，可以设置采样率，只上报一部分错误，减轻服务器压力。

3. 附加上下文

除了错误信息，还可以记录用户的登录状态、操作路径、API 请求参数等，帮助复现问题。

4. 跨域脚本的堆栈

如果引用了 CDN 上的脚本，错误堆栈中可能只有 Script error. 而没有详细信息。需要为脚本添加 crossorigin="anonymous" 属性，并确保服务器响应头包含 Access-Control-Allow-Origin。

总结

本文从 console.log(error) 的底层原理出发，设计了一个兼容所有浏览器的错误格式化函数，并结合 window.onerror 和 unhandledrejection 实现了全局异常捕获与上报。这个方案能够像原生控制台一样输出完整的错误堆栈，同时处理了各种边界情况（非 Error 对象、旧版 IE、循环引用等）。将此模块集成到项目中，你就拥有了一个可靠的前端监控基础，为后续的故障排查和数据分析奠定坚实的基础。

前端异常监控并非一劳永逸，还需要不断优化上报策略、丰富上下文信息，以及结合后端分析工具形成闭环。但至少，从今天开始，你不再对用户的错误一无所知。