Node.js中间件：错误捕获与日志记录中间件

理解Node.js错误处理中间件的执行机制

在Express框架中，中间件的执行遵循严格的线性顺序。普通中间件通常接收三个参数(req, res, next)，负责处理正常请求流；而错误处理中间件必须声明四个参数(err, req, res, next)，这是Express底层通过函数签名长度(Function.length)进行区分的硬性约定。当路由或前置中间件调用next(err)或抛出同步异常时，Express会立即跳过后续所有普通中间件，直接寻找并执行第一个四参数错误处理函数。这种设计确保了错误传播路径的清晰性：正常请求按序向下执行，异常请求则横向跳转至错误处理器。理解这一机制是构建健壮服务的基础，因为若错误处理函数参数数量错误，Express将视其为普通中间件，导致错误被吞没或引发500崩溃。开发者必须明确，四参数中的err用于传递异常对象，req与res提供上下文与响应通道，next则允许错误继续向下游错误处理器传递，形成完整的错误拦截链。

实现统一错误捕获中间件

实现统一错误捕获需同时覆盖同步与异步场景。对于同步代码，可直接使用try...catch捕获后调用next(err)；对于异步操作，推荐在路由中使用async/await配合try...catch，或引入express-async-errors库自动包装路由函数。在错误处理器内部，应定义标准化的响应结构，例如{ success: false, code: 400, message: "参数校验失败", traceId: "xxx" }，并根据错误类型映射对应的HTTP状态码（如400客户端错误、401未授权、500服务器内部错误）。为避免重复发送响应导致ERR_HTTP_HEADERS_SENT异常，必须在调用res.status().json()前严格检查res.headersSent属性。若响应已发出，则仅记录日志并终止流程，确保网络层状态的一致性。通过统一格式，前端可稳定解析错误结构，后端也便于集中监控与告警。

实现结构化日志记录中间件

结构化日志中间件的核心在于记录可检索、可聚合的字段。请求日志应包含时间戳、唯一请求ID(TraceID)、HTTP方法、请求路径、响应状态码及耗时；错误日志则需额外记录错误名称、详细消息、堆栈信息及触发上下文。推荐使用JSON格式输出，便于ELK或Loki等日志系统解析。日志级别需严格划分：info记录常规访问，warn记录业务降级或重试，error记录异常中断。开发阶段可直接使用console.log快速调试，但生产环境必须切换至winston或pino等专业库。这些库支持日志分级过滤、多端输出（文件/控制台/远程服务）、自动轮转与性能优化，能有效避免console在高并发下阻塞事件循环或丢失日志的问题。通过中间件拦截req与res生命周期，可在请求开始时记录info，在错误发生时自动降级为error，实现全链路可观测性。

组合中间件并验证错误链路

中间件的注册顺序直接决定请求处理链路的可靠性。推荐顺序为：首先注册日志与请求ID生成中间件，确保全链路可追踪；其次注册解析器（如express.json()）；接着挂载业务路由与功能中间件；最后在所有路由之后注册全局错误处理中间件。验证时，可发起正常GET请求，预期返回200并输出info级访问日志；在路由中主动抛出业务异常（如throw new CustomError('库存不足', 400)），预期返回400及标准错误JSON，日志记录为warn；最后模拟未捕获的异步拒绝（如未await的Promise），预期被全局错误处理器拦截，返回500并输出error级日志。通过这三类场景测试，可确认错误链路无遗漏且响应格式统一。若发现日志缺失或响应状态异常，需检查中间件注册位置是否被路由覆盖，或next调用是否遗漏err参数。

生产环境避坑与最佳实践

生产环境部署需严格遵循安全与稳定性原则。首要原则是绝不向客户端暴露完整堆栈信息，应通过环境变量NODE_ENV区分环境：开发环境返回详细堆栈便于调试，生产环境仅返回通用错误提示。日志记录必须进行脱敏处理，使用正则或过滤函数剔除密码、Token、身份证号等敏感字段。针对已发送响应的场景，务必在错误处理器中校验res.headersSent，防止二次写入引发进程崩溃。此外，中间件无法捕获事件循环外的异常，需补充process.on('unhandledRejection')与process.on('uncaughtException')作为兜底机制，记录致命错误后执行优雅退出（Graceful Shutdown），避免僵尸进程占用资源。定期审查日志输出策略，确保高并发下日志写入不阻塞主线程，是保障服务长期稳定运行的关键。