文档教程后端【免费下载链接】nodebestpractices✅ The Node.js best practices list (July 2026)项目地址https://gitcode.com/GitHub_Trending/no/nodebestpractices点击查看免费下载导读在 Node.js/Express 现代应用中绝大多数业务代码都运行在 Promise 内部——无论是.then处理器、回调函数还是catch块中。一个反直觉的事实是只要开发者忘了添加.catch子句这些位置抛出的错误不会被uncaughtException事件处理器捕获而是直接消失。本文以 nodebestpractices 仓库中的 捕获未处理的 promise rejection葡萄牙语版 为骨架结合仓库内错误处理实践族的源码级文档讲解如何通过process.on(unhandledRejection)建立兜底机制、如何与集中式错误处理centralized error handler及优雅退出graceful shutdown协同最终让读者掌握一套可落地的零丢失错误异步异常处理方案。问题本质Promise 内的错误会被吞掉一段话解释Node.js 进程级别的错误事件有两个uncaughtException与unhandledRejection。绝大多数开发者只听说过前者甚至很多团队只在process.on(uncaughtException)上挂了处理逻辑。但真相是在 Promise 链中抛出的错误包括.then回调里、catch块里以及 Promise 执行器函数中抛出的错误除非显式添加了.catch子句否则永远不会进入uncaughtException事件它们会被静默吞掉。这正是 nodebestpractices 错误处理实践中的第 2.10 条见 README.md 目录所要解决的核心问题即使你的代码已经订阅了process.uncaughtExceptionPromise 内的异常依然会逃脱捕获、不留任何痕迹。较新版本的 Node 在出现未处理 rejection 时会打印一条警告消息——这有助于发现问题但显然不是一种合格的错误处理方式因为警告只是提示不产生任何结构化处理动作错误可能发生在无人值守的深夜警告转瞬即逝进程仍可能带病运行造成更隐蔽的状态污染。一个错误会凭空消失的代码示例来自原文档的第一个代码示例非常直观——下面的throw不会被任何错误处理器捕获除非注册了unhandledRejectionDAL.getUserById(1).then((johnSnow) { // 这个错误会直接消失 if(johnSnow.isAlive false) throw new Error(ahhhh); });在这个示例中DAL.getUserById(1)返回一个 Promise.then回调里抛出的Error会将该 Promise 变为 rejected 状态。由于没有.catch、也没有任何下游消费方处理这个 rejectionNode.js 事件循环会将其判定为未处理的 Promise rejection——它既不会触发uncaughtException也不会中断请求流程错误就这样被静默丢弃。提示严格相等建议使用参见仓库代码风格实践 ESLint 与代码风格 一族的理念上面的仅是原文档示例原貌实践中更推荐johnSnow.isAlive false。兜底方案订阅unhandledRejection事件为什么不能只靠开发者的自觉最直接的解决方案是永远不要忘记在每个 Promise 链式调用中添加.catch子句并重定向到集中式错误处理器。但 nodebestpractices 明确指出仅仅依赖开发者的纪律来构建错误处理策略是脆弱的fragile。人总会犯错漏写一个.catch是迟早的事——这正是原文档引用 James Nelson 博客时的核心论断如果你可能犯错那么总有一天你会犯If you can make a mistake, at some point you will。因此仓库推荐的优雅做法是注册一个兜底回调process.on(unhandledRejection, callback)——这能保证任何未被本地处理的 Promise 错误最终都能得到它的待遇即进入集中式错误处理流程。完整代码示例捕获未处理 rejection 并与 uncaughtException 协同原文档给出的 JavaScript 示例process.on(unhandledRejection, (reason, p) { // 我刚捕获到一个未处理的 promise rejection // 由于我们已经有了针对未处理错误的后备处理器见下文 // 直接抛出让它去处理 throw reason; }); process.on(uncaughtException, (error) { // 我刚收到一个从未被处理过的错误现在处理它并决定是否需要重启应用 errorManagement.handler.handleError(error); if (!errorManagement.handler.isTrustedError(error)) process.exit(1); });这段代码的设计思路非常精巧值得逐行拆解unhandledRejection回调中throw reason的含义在unhandledRejection事件处理器内部抛出的异常会再次被 Node.js 捕获并触发uncaughtException事件。这样两条漏网之鱼同步未捕获异常与异步未处理 rejection就被统一汇聚到同一个出口——uncaughtException处理器。这是一种单点收口的经典手法不需要在unhandledRejection里复制一套处理逻辑而是把 rejection 重新路由到已有的集中式处理器。errorManagement.handler.handleError(error)调用集中式错误处理器负责记录日志、触发监控指标并决定进程是否崩溃。这正是仓库中 集中式错误处理 实践2.4 条的核心——用一个专门的错误处理对象统一承接所有入口API、定时任务、消息队列消费者、未捕获异常的错误。isTrustedError(error)process.exit(1)区分可信错误operational error与程序缺陷错误programmer error。只有非可信错误才需要退出进程让外部进程守护工具如 systemd、PM2、Kubernetes以干净状态重启。详见仓库 优雅地退出进程2.6 条与 区分运营错误与程序员错误2.3 条。TypeScript 版本原英文版文档提供了对应的 TypeScript 类型标注版本葡萄牙语版未包含这里补充以便完整落地process.on(unhandledRejection, (reason: string, p: Promiseany) { // 捕获未处理的 promise rejection交给下方 uncaughtException 兜底 throw reason; }); process.on(uncaughtException, (error: Error) { // 收到从未被处理的错误处理它并决定是否需要重启 errorManagement.handler.handleError(error); if (!errorManagement.handler.isTrustedError(error)) process.exit(1); });与集中式错误处理协同完整错误流单有unhandledRejection兜底还不够——如果unhandledRejection只是把错误重新抛出却没有一个真正会做事的集中式处理器错误仍然得不到妥善记录与告警。仓库 集中式错误处理 给出了完整的错误流转链路某模块抛出错误 → API 路由捕获错误 → 转发给错误中间件 → 调用集中式错误处理器集中式错误处理器ErrorHandler的职责非常单一而明确让错误可见写入格式良好的日志、触发监控指标如 Prometheus、CloudWatch、DataDog、Sentry 等监控产品并决定进程是否崩溃。仓库中的实现示例// JavaScript 版集中式错误处理器 module.exports.handler new errorHandler(); function errorHandler() { this.handleError async (error, responseStream) { await logger.logError(error); await fireMonitoringMetric(error); await crashIfUntrustedErrorOrSendResponse(error, responseStream); }; }在集中式错误处理文档中unhandledRejection与uncaughtException两个全局事件被明确视为请求级错误处理之外的兜底入口直接汇入同一个处理器process.on(uncaughtException, error { errorHandler.handleError(error); }); process.on(unhandledRejection, (reason) { errorHandler.handleError(reason); });这里有两种可选的汇聚方式仓库文档均有体现汇聚方式做法适用场景直接调用unhandledRejection回调中直接errorHandler.handleError(reason)集中式处理器本身已具备完整的崩溃决策能力重抛汇聚unhandledRejection中throw reason由uncaughtException统一处理已有uncaughtException处理链避免逻辑重复两种方式的共同原则是不要在中间件或散落的代码中处理错误而是统一收口。这也是 集中式错误处理 中强调的反模式——直接在 Express 中间件里写日志、发邮件、判断严重级别的做法会让 Cron 任务、消息队列消费者和测试代码中的错误无人问津。决定是否退出进程isTrustedError 与 isOperationalprocess.exit(1)并非随意为之。仓库 优雅地退出进程 解释了背后的决策模型可信错误operational error例如外部 HTTP 服务连接失败、API 收到非法输入——你完全理解发生了什么以及影响范围记录日志通常就足够了非可信错误programmer error例如读取了 undefined 值、内存泄漏——应用可能已处于不一致状态继续运行只会让后续所有请求都面临失败风险此时最好的选择是退出进程交给进程守护工具以干净状态重启。仓库给出了判断逻辑的经典实现基于error.isOperational标记// 假设开发者将已知的运营错误标记为 error.isOperationaltrue见实践 2.3 process.on(uncaughtException, (error) { errorManagement.handler.handleError(error); if(!errorManagement.handler.isTrustedError(error)) process.exit(1) }); // 集中式错误处理器封装了错误处理相关逻辑 function errorHandler() { this.handleError (error) { return logger.logError(error) .then(sendMailToAdminIfCritical) .then(saveInOpsQueueIfCritical) .then(determineIfOperationalError); } this.isTrustedError (error) { return error.isOperational; } }而在 区分运营错误与程序员错误 中isOperational标记通过统一错误工厂AppError注入// TypeScript 版集中式错误工厂 export class AppError extends Error { public readonly commonType: string; public readonly isOperational: boolean; constructor(commonType: string, description: string, isOperational: boolean) { super(description); Object.setPrototypeOf(this, new.target.prototype); // 恢复原型链 this.commonType commonType; this.isOperational isOperational; Error.captureStackTrace(this); } } // 抛出运营错误可信 throw new AppError(errorManagement.commonErrors.InvalidInput, Describe here what happened, true);这就形成了一条完整链Promise 内的错误 → 未被本地捕获 →unhandledRejection兜底 → 汇聚到集中式处理器 → 依据isOperational决定记录还是崩溃重启。没有unhandledRejection这一步前两者之间的桥就断了。预防胜于兜底先别让错误漏出去兜底机制再完善也只是最后一道防线。nodebestpractices 错误处理实践族还提供了两道前置防线与本文主题直接相关1. 使用内置 Error 对象统一错误结构2.2 条不要抛出字符串或自定义裸类型否则会丢失堆栈信息并破坏模块间互操作。仓库 只使用内置 Error 对象 给出的正例与反例对比// 反模式抛出字符串缺乏堆栈与关键数据属性 if(!productToAdd) throw (How can I add new product when no value provided?); // 正确抛出内置 Error 对象 if(!productToAdd) throw new Error(How can I add new product when no value provided?);在 Promise 场景下的正确写法同文档const addProduct async (productToAdd) { try { const existingProduct await DAL.getProduct(productToAdd.id); if (existingProduct ! null) { throw new Error(Product already exists!); } } catch (err) { // ... } }统一使用内置Error或仅一次扩展出AppError后unhandledRejection兜底收到的reason才有稳定结构集中式处理器才能统一判断isOperational。2. 返回 Promise 前先 await保住完整堆栈2.12 条仓库 返回 Promise 的最佳实践 指出一个与错误被吞同样隐蔽的问题如果函数返回 Promise 时不先await一旦该 Promise 被 reject调用方函数不会出现在堆栈追踪中诊断者拿到的只是残缺信息。反模式示例async function throwAsync(msg) { await null; // 至少 await 一次以真正异步见原文档注 2 throw Error(msg); } async function returnWithoutAwait() { return throwAsync(missing returnWithoutAwait in the stacktrace); } // 堆栈中不会出现 returnWithoutAwait returnWithoutAwait().catch(console.log);正确的做法是显式return awaitasync function returnWithAwait() { return await throwAsync(with all frames present); } // 堆栈中包含 returnWithAwait 帧 returnWithAwait().catch(console.log);这与本文主题互为表里unhandledRejection兜底保证错误不丢失return await保证错误到达兜底时携带完整上下文——二者缺一不可否则即便捕获到了错误也难以定位根因。验证你的直觉三个你以为会打印错误的代码原文档引用了 James Nelson 博客中的一道经典理解测试。请先凭直觉回答以下三段代码哪些会在控制台打印错误Promise.resolve(promised value).then(() { throw new Error(error); }); Promise.reject(error value).catch(() { throw new Error(error); }); new Promise((resolve, reject) { throw new Error(error); });James Nelson 的答案是他原以为三段都会打印错误但现实是许多现代 JavaScript 环境对这三段代码都不会打印任何错误。逐一分析这段测试恰好对应了三种典型的错误被吞路径Promise.resolve(...).then(() { throw ... })——.then回调抛错使 Promise 变为 rejected但无人消费即未处理 rejectionPromise.reject(...).catch(() { throw ... })——.catch内部再次抛错新的 rejected Promise 又无人处理进入未处理状态new Promise((executor) { throw ... })——执行器函数内同步抛错会被 Promise 机制捕获并转为 rejected同样无人消费。这正是原文档观点的延伸作为人类如果可能犯错你迟早会犯。因此我们应该这样设计系统——默认处理错误而不是默认丢弃错误。process.on(unhandledRejection)就是让系统默认处理而非默认丢弃的机制开关。完整落地清单与最佳实践小结将以上实践整合到真实项目中推荐的最小落地步骤统一错误类型基于内置Error建立AppError带isOperational等属性所有模块只抛这一种错误见 只使用内置 Error 对象建立集中式错误处理器实现handleError(error)日志 监控 崩溃决策与isTrustedError(error)见 集中式错误处理注册全局兜底process.on(unhandledRejection, (reason) { throw reason; })配合process.on(uncaughtException, ...)统一收口按可信度决定退出非可信错误调用process.exit(1)由 systemd、PM2 或 Kubernetes 等守护工具重启进程见 优雅退出进程保住堆栈返回 Promise 前显式return await见 返回 Promise 实践测试错误流用测试框架覆盖未处理 rejection等深层错误流确保错误处理器行为符合预期见 测试错误流。最后强调一点边界unhandledRejection兜底是最后一道防线不是偷懒不写.catch的借口。正确的姿态是每一层都尽量本地处理、显式捕获兜底机制只负责接住那些终究漏掉的错误。唯有预防catch/await 收口集中式处理器 兜底unhandledRejection 决策可信度判断与重启四层配合才能让 Node.js 应用中的异步错误真正做到不丢失、可追踪、可处置。赞分享文档教程后端【免费下载链接】nodebestpractices✅ The Node.js best practices list (July 2026)项目地址https://gitcode.com/GitHub_Trending/no/nodebestpractices点击查看免费下载相关推荐Node.js 未处理 Promise rejection 捕捉指南让无声消失的错误无处遁形Node.js 未处理 Promise rejection 捕捉指南让无声消失的错误无处遁形 在 Node.js/Express 应用中绝大多数业务代码运行文档教程后端Node.js 最佳实践捕获未被处理的 Promise 拒绝unhandledRejectionNode.js 最佳实践捕获未被处理的 Promise 拒绝unhandledRejection 导读 在 Node.js/Express 应用中绝大多文档教程后端捕获未处理的 Promise 拒绝unhandledRejectionNode.js 异步错误兜底策略实战捕获未处理的 Promise 拒绝unhandledRejectionNode.js 异步错误兜底策略实战 本文是 nodebestpractices 仓文档教程后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考