先确认现象

收到 ERR_UNCAUGHT_EXCEPTION 错误码时，需要先区分是同步代码还是异步操作触发的。通常异步场景下，进程直接退出并打印堆栈，堆栈顶部往往指向某个 Promise 或 async 函数调用点。确认现象的第一步是查看错误堆栈中是否有 .then()、.catch() 或 async/await 相关调用。

素材1：ERR_UNCAUGHT_EXCEPTION 错误码表示 Node.js 进程中抛出了一个未被任何 try/catch 或 .catch() 捕获的异常。在异步操作中，最常见的情况是 Promise 被 reject 但没有添加 catch 处理器，或者 async 函数内部抛出的错误未被 try/catch 包裹。由于事件循环无法找到对应的错误处理代码，进程会立即退出，并打印出错误堆栈。理解这一点是诊断的第一步：当你看到这个错误时，你需要检查异步操作的错误处理链路是否完整，特别是那些没有显式调用 .catch() 的 Promise 和没有 try/catch 的 async 函数。

看到这个堆栈后，我会先确认异常发生的时间点是否与某个特定请求或定时任务重合。如果是，优先排查对应路径下的异步错误处理是否遗漏。

容易误判的地方

常见做法是把 uncaughtException 和 unhandledRejection 混为一谈。前者是同步或回调中抛出的未被捕获的异常，后者是 Promise 被 reject 但没有任何 .catch() 或 await。虽然两者最终都可能触发进程退出，但诊断路径不同。另一个容易误判的地方是怀疑底层 C++ 模块引发内存错误，但实际上大部分 ERR_UNCAUGHT_EXCEPTION 源自应用层代码，不要一开始就去翻 Node.js 源码。

还有一个细节：在回调式异步操作中，如果开发者忽略了回调的第一个参数（error），错误会静默消失，但后续逻辑可能间接导致未捕获异常。例如 fs.readFile 的回调中未检查 error，却试图操作 data，当文件不存在时 data 为 undefined，后续访问 data.toString() 可能抛出 TypeError，这个错误如果没有被包裹就会变成 uncaughtException。所以排查时不仅要看异常抛出的位置，还要看上游回调是否正确处理了错误参数。

诊断的核心方法

素材2：诊断未捕获异常的核心方法是使用 Node.js 提供的 process.on('uncaughtException') 事件。你可以在应用启动时添加监听器，记录错误的堆栈和上下文信息。例如：process.on('uncaughtException', (err) => { console.error('未捕获异常：', err); process.exit(1); });。这样可以在进程退出前将错误信息持久化到日志文件，便于后续分析。注意，此处不应调用 process.exit(0) 或尝试恢复执行，因为应用状态已经不可预测。更安全的做法是使用 process.on('unhandledRejection') 来捕获未被处理的 Promise rejection，因为 unhandledRejection 并…

我通常会在应用入口同时注册两个监听器：uncaughtException 和 unhandledRejection。前者记录同步及回调异常，后者记录 Promise rejection。注册后运行应用，观察日志中是否有异常详情。如果日志里没有记录，说明监听器没生效或者异常发生在更早的初始化阶段，这时需要检查监听器是否在应用启动代码最前面执行。

操作建议与兜底配置

素材4：建议在开发阶段启用 --unhandled-rejections=strict 模式（或使用环境变量 NODE_OPTIONS='--unhandled-rejections=strict'），这样任何未处理的 Promise rejection 都会直接抛出未捕获异常并导致进程退出，迫使开发者尽早处理错误。生产环境中，建议使用像 pm2 这样的进程管理器，配置进程崩溃后自动重启。同时，务必在应用入口处添加全局的 uncaughtException 和 unhandledRejection 监听器，用于日志记录和优雅关闭（例如关闭数据库连接）。但切记：全局监听器不能替代各级错误处理，它只是兜底措施。

关于优雅关闭，给出一个示例：在 uncaughtException 监听器中，先记录错误，然后调用 server.close() 停止接受新连接，并设置超时强制退出。不要在这里执行复杂清理，避免二次异常。对于数据库连接，可以在 close 回调中释放资源，但需要控制超时时间，防止进程挂起。

验证方法

修改代码后，需要验证错误处理链路是否完整。可以手动在关键异步路径中抛出错误，观察应用是否按照预期记录日志并退出。例如写一个测试路由，内部返回 reject(new Error('test'))，检查是否触发 unhandledRejection 或 uncaughtException。同时检查日志是否包含了堆栈和上下文信息。对于生产环境，建议先在预发布环境开启 strict 模式运行一段时间，确认没有未处理的 rejection 后，再逐步放宽限制。

另一个验证点是检查 pm2 或 docker 的重启策略。当进程因异常退出后，确认自动重启机制生效，并且重启后服务正常。可以查看 pm2 logs 或系统日志确认退出码是否为 1 以及重启计数。

后续维护与风险边界

使用 process.on('uncaughtException') 的风险在于：如果异常导致堆栈污染（例如全局对象被修改），后续请求可能产生更隐蔽的数据错误。因此官方明确不建议在监听器中恢复执行或调用 process.exit(0)。对于 unhandledRejection，未来 Node.js 版本会默认将其视为未捕获异常导致进程退出（目前 12+ 已默认打印警告并退出），所以尽早修复未处理的 rejection 远比依赖全局监听器可靠。

建议后续维护中定期审查错误日志，对频繁出现的未捕获异常进行根因分析。不要依赖全局监听器长期掩盖问题。同时，在代码 review 阶段重点关注 Promise 链是否以 .catch() 结尾、async 函数是否被 try/catch 包裹、回调函数是否检查 error 参数。如果发现遗漏，即使当前没有触发异常也应修复，因为此类隐患可能在特定输入下才暴露。