Node.js日志中错误码含义

Node.js日志中错误码含义与排查要点

一 常见系统错误码与含义

• EACCES：权限不足，常见于绑定低号端口（如80/443）、写受保护目录或访问受限文件。
• EADDRINUSE：端口被占用，启动服务时端口已被其他进程监听。
• ECONNREFUSED：连接被拒绝，目标主机可达但服务未在对应端口监听或被防火墙拒绝。
• ECONNRESET：连接被对端重置，常见于网络不稳定、对端异常关闭或超时设置不当。
• ETIMEDOUT：连接或读写超时，网络延迟高、对端处理慢或超时阈值过低。
• ENETUNREACH：网络不可达，路由或网络设备问题导致无法到达目标网络。
• ENOENT：文件或目录不存在，路径错误、文件未生成或挂载点缺失。
• EBADF / ENOTSOCK：无效文件描述符/不是套接字，文件或套接字已被关闭或传入了错误句柄。
• EADDRNOTAVAIL：地址不可用，绑定到一个本机未配置的地址（如错误的网卡IP）。
• EAFNOSUPPORT：地址族不支持，IP 版本或套接字族配置不匹配。
• EISCONN：套接字已连接，重复调用 connect 等导致状态冲突。
  以上错误码在 Linux/CentOS 等类 Unix 系统与 Node.js 网络/文件操作中非常常见，日志中通常伴随“Error: … code: ‘…’”的提示。

二 Node.js运行时与内置模块错误码

• ERR_OUTOFMEMORY：操作触发内存不足，可能因大对象分配、内存泄漏或 V8 堆限制。
• ERR_STREAM_READ_NOT_IMPLEMENTED：可读流未实现 _read()，自定义流实现不完整。
• ERR_TLS_RENEGOTIATION_FAILED：TLS 重新协商失败，常见于不兼容的客户端/服务器配置。
• ERR_UNKNOWN_BUILTIN_MODULE：Node.js 内部错误，通常不应由用户代码触发。
• ERR_STDOUT_CLOSE / ERR_STDERR_CLOSE：用户代码尝试关闭 process.stdout/stderr，Node.js 不允许。
• ERR_FS_WATCHER_ALREADY_STARTED / ERR_FS_WATCHER_NOT_STARTED：fs.watch 监听器重复启动或未启动即操作。
• ERR_HTTP2_ALREADY_SHUTDOWN / ERR_HTTP2_ERROR：HTTP/2 会话重复关闭或协议错误。
• ERR_INVALID_REPL_HISTORY / ERR_INVALID_REPL_TYPE：REPL 历史文件损坏或启动参数与 REPL 不兼容。
• ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK：ESM 加载器声明 format: ‘dynamic’ 但未提供 dynamicInstantiate 钩子。
• ERR_VM_MODULE_NOT_LINKED：ESM 模块未成功链接即实例化。
• ERR_ZLIB_BINDING_CLOSED：在 zlib 对象关闭后仍尝试使用。
• ERR_ENTRY_TYPE_MISMATCH：入口文件类型与 package.json 的 “type”: “module”/“commonjs” 或 –entry-type 不匹配。
  这些代码多见于 Node.js 内部模块与运行时约束，定位时优先检查对应 API 的使用约束与模块系统配置。

三 HTTP状态码与日志解读

• 1xx 信息性：请求已被接收，继续处理。
• 2xx 成功：如 200 OK、201 Created，请求成功处理。
• 3xx 重定向：如 301 Moved Permanently、302 Found，需要进一步操作完成请求。
• 4xx 客户端错误：如 400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found，请求有误或权限不足。
• 5xx 服务器错误：如 500 Internal Server Error、503 Service Unavailable，服务器处理异常或过载。
  在 Node.js（如 Express）中，可通过 res.status(code).send(…) 设置状态码；日志中 HTTP 状态码与响应体、堆栈一起出现，有助于快速判断是客户端问题还是服务端异常。

四 快速排查步骤

• 定位错误码与上下文：查看完整错误堆栈、错误消息、发生时间、请求路径/目标地址、进程与线程信息。
• 网络类错误（如 ECONNREFUSED/ECONNRESET/ETIMEDOUT/ENETUNREACH）：
  • 确认目标服务已启动并监听正确端口（如 ss -ltnp | grep :端口 或 netstat -tulpen | grep :端口）。
  • 检查本机与目标主机的防火墙/安全组、路由与网络质量；必要时调整超时与重试策略。
• 端口占用（EADDRINUSE）：
  • 查找并终止占用进程（如 lsof -i :端口 或 netstat -tulpen | grep :端口 获取 PID，再 kill -9 PID），或更换端口。
• 权限类（EACCES）：
  • 避免以 root 直接运行；为应用配置最小权限；必要时调整目录/文件权限或以具备权限的用户运行。
• 文件不存在（ENOENT）：
  • 校验配置/日志/上传目录是否存在并可写；修正相对路径与工作目录；容器/挂载卷是否正确。
• 运行时/模块错误（如 ERR_OUTOFMEMORY/ERR_STREAM_READ_NOT_IMPLEMENTED）：
  • 检查代码路径是否触发未实现接口或资源未正确释放；监控内存与 GC；升级 Node.js 版本并核对 ESM/CommonJS 配置一致性。
• HTTP 状态码（4xx/5xx）：
  • 结合业务日志与中间件栈定位路由、鉴权、参数校验与上游依赖；对 5xx 重点排查未捕获异常、数据库/缓存可用性、第三方服务健康度。
    以上步骤可配合进程管理工具（如 PM2）与监控告警，缩短恢复时间并降低复发概率。