JavaScript 中可通过监听 unhandledrejection(浏览器)或 process.on('unhandledRejection')(Node.js)事件捕获未处理的 Promise 拒绝,事件对象含 reason 和 promise,宜尽早注册并结合 rejectionhandled/rejectionHandled 避免误报。

在 JavaScript 中,未被 catch 捕获的 Promise 拒绝(rejected)会触发全局事件,可通过监听 unhandledrejection 事件来统一捕获和处理。
监听 unhandledrejection 事件
该事件在 Promise 被拒绝且没有绑定任何 catch 或 then(null, ...) 处理器时触发。推荐在脚本最开始就注册监听器,确保覆盖所有异步路径:
- 监听器必须在全局作用域(如
window或self)注册,Node.js 环境则用process.on('unhandledRejection') - 事件对象包含
reason(拒绝原因,通常是 Error 实例或任意值)和promise(被拒绝的 Promise 实例) - 可在此记录错误、上报监控系统,或调用
console.error提示开发人员
避免重复捕获与误报
同一个 Promise 拒绝可能触发多次事件(例如在多个微任务队列中未及时处理),需注意:
- 浏览器会在 Promise 被拒绝后约 1 个事件循环周期内触发该事件;若之后补上
catch,部分环境(如 Chrome)会自动取消事件(称为“rejection regained”) - 可通过
event.preventDefault()阻止默认行为(如控制台警告),但不推荐完全屏蔽,除非你有完善的错误兜底逻辑 - 不要在监听器里抛出新异常,否则可能引发无限循环或被忽略
配合 rejectionHandled 事件做精细控制
当一个被拒绝的 Promise 后续被 catch 处理时,会触发 rejectionhandled 事件。可结合两者追踪 Promise 生命周期:
立即学习“Java免费学习笔记(深入)”;
- 在
unhandledrejection中缓存 promise 引用或 ID,标记为“待处理” - 在
rejectionhandled中清除对应标记,避免误报 - 适用于需要严格区分“真正未处理错误”和“延迟处理”的监控场景
Node.js 环境中的等价方案
Node.js 不支持 unhandledrejection 浏览器事件,但提供对应的 process 事件:
- 使用
process.on('unhandledRejection', (reason, promise) => { ... }) - 同样建议尽早注册(如入口文件顶部),并注意:该事件不会阻止进程退出——若拒绝未被处理且无其他异步操作,Node.js 进程仍可能退出
- 可配合
process.on('rejectionHandled', ...)实现类似浏览器的行为


















