window.onerror是浏览器提供的全局错误监听接口，能够在JavaScript运行时发生错误时触发回调，是前端错误监控体系中最基础的核心能力之一。理解它的拦截机制，能够帮助开发者更精准地捕获线上异常，及时定位问题。
window.onerror的基本用法
window.onerror是一个全局事件处理函数，我们可以直接为其赋值一个回调函数，当页面中发生未被捕获的JavaScript错误时，该回调就会被执行。基本语法如下：
// 定义window.onerror的回调函数
window.onerror = function(message, source, lineno, colno, error) {
// message：错误信息描述
// source：发生错误的脚本URL
// lineno：发生错误的行号
// colno：发生错误的列号
// error：错误对象，包含更详细的堆栈信息
console.log('捕获到错误：', message);
console.log('错误来源：', source);
console.log('错误行号：', lineno);
console.log('错误列号：', colno);
console.log('错误对象：', error);
// 这里可以将错误信息上报到监控系统
return true; // 返回true可以阻止浏览器默认的错误提示
};
window.onerror的拦截机制解析
触发条件
window.onerror的回调会在以下场景中触发：
- JavaScript运行时错误，比如调用未定义的函数、访问不存在的属性、语法错误等
- 资源加载错误？不对，资源加载错误（如图片、脚本加载失败）不会触发window.onerror，这类错误需要通过addEventListener监听error事件，并且要区分事件的目标是否是元素
- 异步代码中的错误，比如setTimeout、Promise中的未捕获错误？这里需要注意，Promise的未捕获错误默认不会触发window.onerror，需要额外监听unhandledrejection事件
参数含义详解
回调函数的五个参数各有作用，具体说明如下：
| 参数名 | 含义 | 备注 |
|---|---|---|
| message | 错误的描述信息 | 通常是错误类型的简短说明 |
| source | 发生错误的脚本文件的URL | 如果是内联脚本，可能是当前页面的URL |
| lineno | 错误发生的行号 | 从1开始计数 |
| colno | 错误发生的列号 | 从1开始计数 |
| error | 错误对象 | 包含stack堆栈信息，部分浏览器可能不支持该参数 |
拦截范围与限制
window.onerror的拦截能力存在一定边界：
- 只能捕获同一域下的脚本错误，如果是跨域加载的脚本发生错误，默认情况下只能获取到Script error.的错误信息，无法获取详细的错误堆栈，需要在跨域脚本的标签上添加crossorigin属性，同时服务器返回对应的CORS头才能获取完整信息
- 无法捕获Promise的未处理拒绝错误，这类错误需要单独监听
unhandledrejection事件 - 无法捕获网络请求失败、资源加载失败等非JavaScript运行时的错误
- 如果错误被try-catch捕获，那么window.onerror也不会触发
window.onerror的最佳实践
1. 合理处理跨域脚本错误
对于跨域加载的脚本，需要在script标签上添加crossorigin属性，示例如下：
<script src="https://cdn.ipipp.com/library.js" crossorigin="anonymous"></script>
同时服务器需要返回Access-Control-Allow-Origin响应头，允许当前域访问该脚本的资源，这样才能在window.onerror中获取到跨域脚本的完整错误信息。
2. 结合unhandledrejection捕获Promise错误
为了覆盖Promise的未捕获错误，需要额外添加监听：
// 监听Promise未处理的拒绝错误
window.addEventListener('unhandledrejection', function(event) {
console.log('捕获到Promise未处理错误：', event.reason);
// 上报错误信息
event.preventDefault(); // 阻止默认的错误提示
});
// 同时保留window.onerror处理普通JS错误
window.onerror = function(message, source, lineno, colno, error) {
// 错误上报逻辑
return true;
};
3. 错误上报的注意事项
在错误上报时，需要注意以下几点：
- 上报前可以对错误信息进行过滤，避免重复上报相同的错误，比如同一个错误在短时间内多次触发，可以设置去重逻辑
- 上报的信息要包含足够的上下文，比如当前页面的URL、用户的操作路径、设备信息等，方便后续排查问题
- 上报请求要使用同步请求或者可靠的异步请求，避免因为页面卸载导致上报失败，也可以使用navigator.sendBeacon方法发送上报请求
4. 避免错误回调本身抛出异常
window.onerror的回调函数如果本身抛出错误，可能会导致无限循环的错误触发，因此回调内部的逻辑要尽量简洁，避免复杂的操作，同时可以添加try-catch包裹回调逻辑：
window.onerror = function(message, source, lineno, colno, error) {
try {
// 错误上报逻辑
const errorInfo = {
message: message,
source: source,
lineno: lineno,
colno: colno,
stack: error && error.stack
};
// 使用sendBeacon上报
navigator.sendBeacon('/api/report-error', JSON.stringify(errorInfo));
} catch (e) {
// 回调内部错误不做处理，避免循环触发
}
return true;
};
常见问题说明
很多开发者会混淆<code>标签和code()函数调用，在描述代码相关术语时，如果是突出显示代码片段，使用code标签，比如这里提到的window.onerror就是代码术语，而如果是函数调用则直接写window.onerror()，不需要额外加标签。另外，HTML标签名称在正文描述时需要转义，比如提到输入框标签时应该写<input>，而不是直接写。
在实际开发中，window.onerror是前端监控的第一道防线，结合其他错误捕获手段，可以构建完整的错误监控体系，帮助开发者快速定位和解决线上问题，提升用户体验。
window.onerrorJavaScript错误捕获前端错误监控错误拦截机制修改时间：2026-06-23 19:39:52