前端日志记录与上报，是指利用JavaScript在浏览器环境中采集运行时错误信息、性能数据与用户行为轨迹，并通过网络请求将数据发送到服务端进行存储和分析。它能够帮助开发者还原线上真实故障场景，避免依赖用户零散且不准确的口头描述。
一、前端日志监控的定位与价值
传统前端开发中，代码部署后往往处于不可观测状态。用户遇到白屏、接口失败或点击无响应时，开发者通常无法第一时间感知，只能等待客服反馈。而用户的描述常常缺少关键操作步骤，导致问题排查耗时且难以复现。前端日志监控相当于为每个浏览器会话装上黑匣子，持续记录程序运行时的异常事件，为后续定位提供依据。
除了捕获错误，前端日志还可以反映性能瓶颈。比如某个组件渲染耗时过长、某个接口失败率突然上升，这些都可以通过定时采集与主动上报提前发现。对于没有独立运维平台支持的团队，一套轻量的JavaScript日志方案能够覆盖大部分线上可观测性需求，并且接入成本很低。
二、全局错误与资源加载错误捕获
在JavaScript中，全局异常监听接口window.onerror是最基础的错误捕获方式。它可以捕获未被try-catch处理的同步运行时错误，以及部分异步错误。该接口的回调函数会收到错误消息、脚本地址、行号、列号和错误对象，这些信息足以帮助定位出现问题的代码位置。
不过window.onerror无法捕获资源加载错误，例如<img>或<script>标签加载失败时，错误事件不会冒泡到window对象。针对这类错误，需要在捕获阶段监听error事件，并判断事件目标是否为对应的HTML元素。下面的代码展示了两种错误捕获的组合使用方式。
// 监听全局JS运行时错误
window.onerror = function(message, source, lineno, colno, error) {
const log = {
type: 'js_error',
message: message,
source: source,
lineno: lineno,
colno: colno,
stack: error && error.stack
};
sendLog(log);
};
// 捕获资源加载错误，使用捕获阶段
window.addEventListener('error', function(e) {
if (e.target && (e.target.tagName === 'IMG' || e.target.tagName === 'SCRIPT')) {
const resLog = {
type: 'resource_error',
url: e.target.src || e.target.href
};
sendLog(resLog);
}
}, true);
function sendLog(data) {
// 此处可替换为真实上报地址
const url = 'https://log.ipipp.com/collect';
const body = JSON.stringify(data);
if (navigator.sendBeacon) {
navigator.sendBeacon(url, body);
} else {
fetch(url, { method: 'POST', body: body, keepalive: true });
}
}
上述示例中，window.onerror负责收集脚本运行时的同步异常，而捕获阶段的error事件则专门用于识别图片或脚本等静态资源加载失败的情况。两者配合后，可以覆盖前端错误场景中的大部分基础类型。
三、Promise异常与网络请求日志
现代前端项目中大量使用Promise处理异步流程，而未处理的Promise拒绝不会触发window.onerror，必须通过unhandledrejection事件单独采集。该事件能够提供拒绝原因，通常包含错误消息和堆栈信息，是排查异步逻辑问题的重要依据。
同时，业务接口返回的HTTP状态码异常或约定错误码，也属于必须上报的逻辑异常。与其在业务代码中散落处理，不如在统一请求封装层拦截失败响应，记录请求地址、状态码和错误信息。这样既能保证日志格式一致，又能避免遗漏。以下示例演示了Promise异常捕获与fetch请求封装的结合。
// 捕获未处理的Promise拒绝
window.addEventListener('unhandledrejection', function(e) {
const reason = e.reason;
sendLog({
type: 'promise_error',
message: reason && reason.message,
stack: reason && reason.stack
});
});
// 统一请求上报
async function request(url, options) {
try {
const res = await fetch(url, options);
if (!res.ok) {
sendLog({
type: 'http_error',
url: url,
status: res.status
});
}
return res;
} catch (err) {
sendLog({
type: 'network_error',
url: url,
message: err.message
});
throw err;
}
}
通过unhandledrejection可以捕获未显式处理的Promise失败，避免异步流程中的异常被静默吞掉。而请求层的统一拦截则把接口调用质量问题也纳入监控范围，使前端日志不仅覆盖代码错误，还能反映服务端与网络链路的状态。
四、上报策略与可靠性保障
如果每次捕获到错误都立即发送网络请求，错误爆发时可能淹没正常业务流量。因此通常需要采用采样上报策略，例如只对百分之十的用户进行全量采集，其余用户仅上报致命错误。这样可以控制日志总量，同时保留足够样本用于分析。
页面卸载是日志丢失的高危场景。当用户关闭页面或跳转时，普通的fetch请求往往会被浏览器取消。此时应优先使用navigator.sendBeacon发送数据，它能够在页面卸载后继续完成请求。为了应对弱网或离线情况，还可以结合localStorage暂存未成功上报的日志，在下次启动时进行补发。下面的表格对比了三种常见上报方式的可靠性与适用场景。
| 方式 | 可靠性 | 适用场景 |
|---|---|---|
| fetch | 中 | 页面活跃时常规上报 |
| sendBeacon | 高 | 页面关闭前兜底发送 |
| localStorage+重试 | 高 | 弱网或离线暂存 |
在设计上报策略时，还应注意控制请求频率和数据体积。错误的堆栈信息可能较长，可以截断或压缩后再上报，避免单条日志过大。采样规则也应根据业务阶段灵活调整，例如灰度发布期间提高采集比例，稳定运行后适当降低。
五、日志字段设计与隐私合规
一条有用的前端日志至少应当包含发生时间、错误类型、页面路径和用户标识。时间用于排序，类型用于分类，页面路径用于定位页面，用户标识用于聚合统计。字段设计越清晰，后续分析越容易。
隐私合规是不可忽视的问题。日志中不应包含手机号、身份证号等敏感信息，避免触碰数据安全红线。可以通过白名单机制控制上报字段，并对page_url、user_id等标识做脱敏处理。服务端在接收日志后按类型建立索引，可以在灰度发布后快速观察错误率波动，判断新版本是否引入回归问题。
同时，日志中还应包含应用版本、构建号等环境信息。当线上同时存在多个版本时，这些字段能够帮助开发者快速判断问题是否只在特定版本中出现，从而缩小排查范围。
六、完整封装与接入建议
将前面介绍的能力合并到一个类中，可以形成轻量可复用的前端日志组件。在项目入口文件初始化一次，即可自动监听全局错误、资源加载错误和未处理的Promise拒绝。下面的代码直接可用，只需要修改上报地址和采样比例。
class FrontLog {
constructor(opt) {
this.url = opt.url || 'https://log.ipipp.com/collect';
this.sample = opt.sample || 1;
this.bind();
}
bind() {
window.onerror = (msg, src, line, col, err) => {
this.report({ type: 'js_error', msg: msg, src: src, line: line, col: col, stack: err && err.stack });
};
window.addEventListener('error', (e) => {
if (e.target && e.target.tagName) {
this.report({ type: 'res_error', url: e.target.src || e.target.href });
}
}, true);
window.addEventListener('unhandledrejection', (e) => {
this.report({ type: 'promise_error', msg: e.reason && e.reason.message });
});
}
report(data) {
if (Math.random() > this.sample) return;
data.t = Date.now();
const body = JSON.stringify(data);
if (navigator.sendBeacon) {
navigator.sendBeacon(this.url, body);
} else {
fetch(this.url, { method: 'POST', body: body, keepalive: true });
}
}
}
new FrontLog({ url: 'https://log.ipipp.com/collect', sample: 0.1 });
前端日志监控并非接入后就能一劳永逸。开发者需要定期审视上报量是否合理、错误分类是否准确、采样策略是否适应业务变化。随着业务规模增长，可以逐步引入日志聚合查询、告警通知等能力，让监控真正服务于线上稳定性。
综合来看，前端日志记录与上报的核心在于错误捕获、可靠传输和隐私保护三个环节。通过合理组合window.onerror、error、unhandledrejection等事件，并在请求层统一拦截异常，可以构建一个覆盖大多数场景的监控基础。建议从轻量封装开始，逐步完善采样、重试、聚合和告警机制，使线上问题能够被更早发现和定位。
JavaScript前端日志错误监控修改时间：2026-08-04 13:06:41