• 文档
• 教程
• 后端

导读

本文基于 nodebestpractices 仓库中《集中处理错误，而非在中间件中处理》这一最佳实践，讲解如何将 Node.js 应用的错误处理逻辑收敛到一个专用、集中的错误处理对象中。你将掌握一套可复用的错误处理架构：从模块抛错 → API 路由捕获 → 中间件转发 → 集中式处理器统一处置的完整链路，并学会区分「业务错误」与「程序错误」，为日志、监控与优雅重启建立统一的出口。

为什么必须集中处理错误

在没有一个专用错误处理对象时，错误处理方式很容易变得不一致：Web 请求中抛出的错误、启动阶段抛出的错误、定时任务（Cron/Job）抛出的错误，往往会被不同位置的代码以不同方式处理，最终导致一些重要错误被掩盖在雷达之下，得不到应有的关注。

集中式错误处理对象（Centralized Error Handler）的核心职责是让错误可见，典型手段包括：

• 写入格式良好的日志（logger）；
• 向监控产品上报指标（如 Prometheus、CloudWatch、DataDog、Sentry 等）；
• 决定进程是否应当崩溃退出。

大多数 Web 框架（Express、Koa）都提供了错误捕获中间件机制，而一个常见但错误的实践就是把错误处理逻辑直接写进这个中间件里。这样做的问题在于：无法复用同一套处理器去覆盖不同场景下的错误——比如定时任务、消息队列订阅者、未捕获异常等非 Web 接口场景。因此，错误中间件的职责应该仅仅是「捕获并转发」，真正的处理逻辑必须交给集中的错误处理对象。

一个典型的错误处理流程如下：

1. 某个业务模块抛出错误；
2. API 路由捕获到错误（同步与异步都要捕获）；
3. 错误被传播给负责捕获请求级错误的中间件；
4. 中间件调用集中式错误处理器；
5. 处理器判定该错误是否为「可信错误」（非业务错误，即非操作型错误），如果是不可信错误则优雅地重启应用。

这一流程在整个项目中的定位，可参见 README.md 第 2.4 节：「处理逻辑（如日志、崩溃决策、监控指标）应封装在专用且集中的对象中，让所有入口（API、Cron、定时任务）在错误发生时都调用它」——否则将导致代码重复，并很可能出现处理不当的错误。

典型错误流：模块 → 路由 → 中间件 → 集中处理器

下面这段 JavaScript 代码完整展示了推荐的分层错误流转方式：

// DAL 层，这里我们不处理错误 DB.addDocument(newCustomer, (error, result) => { if (error) throw new Error("Great error explanation comes here", other useful parameters) }); // API 路由代码，同时捕获同步与异步错误，并转发给中间件 try { customerService.addNew(req.body).then((result) => { res.status(200).json(result); }).catch((error) => { next(error) }); } catch (error) { next(error); } // 错误处理中间件，委托集中式错误处理器处理错误 app.use(async (err, req, res, next) => { const isOperationalError = await errorHandler.handleError(err); if (!isOperationalError) { next(err); } });

各层的分工值得仔细品味：

• DAL 层：只负责抛出语义清晰的错误，不掺杂任何处理逻辑；
• 路由层：用try/catch捕获同步错误，用 Promise 链的.catch()捕获异步错误，统一next(error)上抛——这正是 asyncerrorhandling.korean.md 中「用 Promise/async-await 处理异步错误」所强调的做法，回调嵌套式错误检查会让代码难以阅读和推理；
• 中间件层：只做「转发」，通过await errorHandler.handleError(err)把错误交给集中处理器，并根据返回值（是否操作型错误）决定是否继续上抛。

在完整的生产实践中，除了 Express 中间件，还需要为「进程级」错误建立同样的出口。集中处理器同样应该被uncaughtException与unhandledRejection事件调用（对应仓库中 catchunhandledpromiserejection.korean.md 与 shuttingtheprocess.korean.md 的实践），例如：

process.on("uncaughtException", (error) => { errorHandler.handleError(error); }); process.on("unhandledRejection", (reason) => { errorHandler.handleError(reason); });

这样一来，无论是请求内错误、被遗漏的 Promise 拒绝，还是从未被捕获的异常，最终都会汇聚到同一个处理出口。

在专用对象中处理错误：核心实现

集中式错误处理器的推荐形态是一个专门的错误处理对象，将所有「动作」内聚封装：

module.exports.handler = new errorHandler(); function errorHandler() { this.handleError = async function(err) { await logger.logError(err); await sendMailToAdminIfCritical; await saveInOpsQueueIfCritical; await determineIfOperationalError; }; }

对应 TypeScript 版本则更清晰地表达为一个类：

class ErrorHandler { public async handleError(error: Error, responseStream: Response): Promise<void> { await logger.logError(error); await fireMonitoringMetric(error); await crashIfUntrustedErrorOrSendResponse(error, responseStream); }; } export const handler = new ErrorHandler();

这里的每一步操作（记日志、发告警邮件、入运维队列、判定是否为操作型错误）都以可独立替换、可测试的形态沉淀在对象内部。值得注意的是，handleError是异步的，这意味着所有子任务都应以 Promise 链（.then(...)）或await顺序编排，保证错误处理本身不会因为回调嵌套而再次引入混乱。

反模式：把错误处理写死在中间件里

以下是被明确否定的写法——中间件直接承担了日志、邮件告警与可信度判定等全部职责：

// 中间件直接处理错误——那谁来处理 Cron 任务和测试中的错误呢？ app.use((err, req, res, next) => { logger.logError(err); if (err.severity == errors.high) { mailer.sendMail(configuration.adminMail, 'Critical error occured', err); } if (!err.isOperational) { next(err); } });

这段代码看似「方便」，但存在三个致命缺陷：

1. 覆盖面不足：中间件只服务于 HTTP 请求链路，Cron 任务、消息队列订阅者、测试代码中抛出的错误完全没有入口；
2. 逻辑泄漏：日志格式、告警策略、监控指标散落在中间件中，无法被其他场景复用；
3. 职责混乱：中间件本应是「请求上下文」的一环，混入错误处理会让它既管请求又管故障，难以独立测试与演进。

仓库在 README.md 第 2.4 节 的 "Otherwise" 部分给出了同样的警告：不在单一位置处理错误，将导致代码重复，并且很可能产生处理不当的错误。

与相邻最佳实践的组合：让集中处理器真正可落地

集中式错误处理器要正确工作，离不开项目里几个相邻实践的支持，它们是 sections/errorhandling 目录下的姊妹篇：

1. 区分操作型错误与程序错误（operationalvsprogrammererror.korean.md）：操作型错误（如外部服务连接失败、输入校验失败）是可预知、可恢复的，记日志即可；程序错误（如读取未定义值、连接池内存泄漏）意味着应用可能处于不一致状态，最好的处理是重启。集中处理器中determineIfOperationalError/crashIfUntrustedErrorOrSendResponse的判断依据，正是错误对象上的isOperational标记：

const myError = new Error("How can I add new product when no value provided?"); myError.isOperational = true;

2. 只使用内置 Error 对象（useonlythebuiltinerror.korean.md）：错误对象应统一为 Node 内置Error的实例，避免抛出字符串或自定义类型导致instanceof契约被破坏、堆栈信息丢失。推荐的做法是派生统一的AppError基类：

function AppError(name, httpCode, description, isOperational) { Error.call(this); Error.captureStackTrace(this); this.name = name; //...other properties assigned here }; AppError.prototype = Object.create(Error.prototype); AppError.prototype.constructor = AppError; module.exports.AppError = AppError; // 客户端抛异常 if (user == null) throw new AppError(commonErrors.resourceNotFound, commonHTTPErrors.notFound, "further explanation", true)

3. 捕获未处理的 Promise 拒绝（catchunhandledpromiserejection.korean.md）：process.on('unhandledRejection', ...)作为兜底，将漏网的 Promise 错误重新抛给uncaughtException处理链，最终仍收敛到集中处理器：

process.on('unhandledRejection', (reason, p) => { // 已有兜底处理器，抛出去让它统一处理 throw reason; }); process.on('uncaughtException', (error) => { errorManagement.handler.handleError(error); if (!errorManagement.handler.isTrustedError(error)) process.exit(1); });

4. 优雅退出进程（shuttingtheprocess.korean.md）：当遇到不可信错误时，集中处理器应判定isTrustedError(error)，若返回 false 则process.exit(1)，交由 PM2、Forever、Docker 等重启机制以干净状态恢复服务。

一张图看懂整体错误流

下图展示了「错误产生 → 捕获 → 集中处置」的完整参与方与流转路径，是理解本文架构的最佳视觉辅助：

行业共识：为什么业界都推荐集中处理

仓库中引用了三篇「Node.js 错误处理」主题下的高排名博客，从不同角度印证了集中式处理的必要性：

Joyent 博客（"Node.js error handling" 关键词排名第 1）：「……你可能会在调用栈的多个层级处理同一个错误。当底层除了把错误传播给调用方之外做不了任何有用的事时，这种情况就会发生。通常只有最顶层的调用方才知道合适的响应是什么——是重试操作、向用户报告错误，还是做别的。但这不意味着你应该把所有错误都报告给单一的顶层回调，因为那个回调本身无法知道错误发生在什么上下文……」

JS Recipes 博客（"Node.js error handling" 关键词排名第 17）：「……仅 Hackathon Starter 的 api.js 控制器中就有超过 79 处错误对象。逐一处理每个错误将导致海量代码重复。你能做的最好的下一步，就是把所有错误处理逻辑委托给一个 Express 中间件……」

Daily JS 博客（"Node.js error handling" 关键词排名第 14）：「……你应该在错误对象中设置有用的属性，但使用这类属性时必须保持一致。并且不要跨层传递：HTTP 错误不应出现在数据库代码中。对浏览器开发者而言，Ajax 错误应存在于与服务器通信的代码里，而不是处理 Mustache 模板的代码中……」

这三段引用共同指向两个结论：重复处理 = 重复代码 = 高风险；错误对象需要携带一致的结构化属性（如isOperational、severity），这是集中处理器能够统一决策的前提。

落地清单

• 建立唯一的errorHandler单例对象，封装日志、告警、监控、可信度判定四类动作；
• 所有入口（API 路由、Cron、消息队列、进程级事件）都把错误转发给该对象；
• 中间件只做捕获与转发，不承载任何处理逻辑；
• 用isOperational等属性标记错误性质，让处理器能够区分「记录即可」与「必须重启」；
• 用内置Error派生统一错误基类，保证堆栈信息与instanceof契约不丢失；
• 注册unhandledRejection/uncaughtException兜底，确保没有错误会静默消失。

以上实践均可在仓库 sections/errorhandling 目录中找到对应的完整论述与代码示例，可作为实现时的直接参考。

• 文档
• 教程
• 后端