UnhandledRejection: 未捕获的Promise错误

Question

在Node.js项目中，常因异步操作未正确处理Promise拒绝而触发“UnhandledRejection: 未捕获的Promise错误”。例如数据库连接失败或API请求超时后未使用`.catch()`或`try/catch`捕获异常，导致进程崩溃。尽管该警告提示可被监听`unhandledRejection`事件缓解，但治本之策是确保每个Promise都有显式错误处理。如何在大型项目中系统性避免此类问题？

Answer 1

1. 问题的起源：什么是 UnhandledRejection？

在 Node.js 中，当一个 Promise 被拒绝（rejected）但没有被显式捕获时，会触发 'unhandledRejection' 事件。Node.js 会打印警告信息，如：

(node:1234) UnhandledPromiseRejectionWarning: Error: connect ECONNREFUSED
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1146:16)

虽然进程不会立即退出（在较新版本中默认行为已改变），但这类错误表明代码存在潜在缺陷，尤其在大型项目中容易引发服务不稳定或数据不一致。

常见诱因包括：

• 数据库连接失败未被捕获
• HTTP 请求超时未使用 .catch()
• 异步中间件中抛出异常未处理
• EventEmitter 异步监听器中返回的 Promise 未处理

2. 常见错误模式分析

错误写法	问题描述	修复建议
someAsyncFunc().then(result => {...})	缺少 .catch() 处理拒绝状态	添加 .catch() 或使用 try/catch（async/await）
app.get('/', async (req, res) => { await db.query(...); })	async 函数内部异常未被捕获，导致 Promise 拒绝未处理	包裹 try/catch 或使用错误处理中间件
eventEmitter.on('data', () => someAsyncOp())	事件回调返回的 Promise 未被处理	显式处理或封装为 safeEmit

3. 技术演进路径：从被动监听到主动防御

1. 初级防御：监听 unhandledRejection 事件

   process.on('unhandledRejection', (reason, promise) => {
     console.error('Unhandled Rejection at:', promise, 'reason:', reason);
     // 可记录日志，但不应作为主要解决方案
   });

2. 中级策略：统一错误处理中间件（Express 场景）

   const asyncHandler = fn => (req, res, next) =>
     Promise.resolve(fn(req, res, next)).catch(next);
   
   app.get('/user/:id', asyncHandler(async (req, res) => {
     const user = await User.findById(req.params.id);
     if (!user) throw new Error('User not found');
     res.json(user);
   }));

3. 高级架构：全局 Promise 封装与监控 使用代理或装饰器对关键异步调用进行包装，确保每个 Promise 都有兜底处理。

4. 系统性解决方案设计

graph TD
  A[异步操作发起] -- Promise 返回 --> B{是否被 await / .catch?}
  B -- 否 --> C[触发 unhandledRejection]
  B -- 是 --> D[正常错误处理流程]
  D --> E[业务逻辑捕获]
  E --> F[传递至全局错误处理器]
  F --> G[日志记录 & 监控告警]
  C --> H[进程级监听，用于兜底报警]

5. 工程化手段保障：CI/CD 与静态分析

通过工具链提前发现潜在的未处理 Promise：

• ESLint 规则：

  "rules": {
    "require-await": "warn",
    "no-async-promise-executor": "error",
    "prefer-promise-reject-errors": "warn"
  }

• TypeScript 静态检查：结合 strictNullChecks 和自定义类型守卫，提升异常路径可见性。
• 自动化测试覆盖：模拟网络故障、数据库断连等场景，验证错误是否被正确传播和处理。

6. 架构层面的最佳实践

在微服务或大型单体架构中，推荐以下模式：

• 分层错误处理：DAO 层抛出具体错误 → Service 层转换为业务异常 → Controller 层统一响应格式
• 异步任务队列化：将高风险异步操作放入 Bull、Kue 等队列系统，支持重试与死信机制
• 运行时监控集成：结合 Sentry、Datadog 等工具捕获 unhandledRejection 并关联上下文（trace ID、用户信息）