Node.js日志中错误码含义

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

先说一个背景：在Node.js应用中，错误码是定位和排查问题的第一信号。无论是系统级错误、运行时异常，还是HTTP请求的响应状态，日志里留下的那个简短英文代码，往往直接指向问题根源。以下是从实战中梳理出来的三种常见错误码类型及其排查思路。

一 常见系统错误码与含义

Node.js底层依赖libuv，很多系统层面的错误在日志里表现得很直接——比如权限、端口、网络连接、文件读写这一类。这里把最常碰到的几个列出来：

• EACCES：权限被拒。这事儿常发生在你试图绑定80或443这样的特权端口时，或者往一个受保护的目录里写文件。说白了，进程权限不够。
• EADDRINUSE：端口已被占用。启动服务时报这个，说明有另一个进程已经占着那个端口不放。用 lsof -i :端口号 或者 netstat -tulpen | grep :端口号 就能查出来是谁。
• ECONNREFUSED：连接被拒绝。目标主机是活的，但它那个端口上没有服务在监听，或者防火墙一口回绝了你。
• ECONNRESET：连接被重置。这多半是网络不稳定、对端突然挂了，或者超时了。别急着怀疑代码，先看看链路。
• ETIMEDOUT：超时了。要么网络延迟太高，要么对端处理太慢，要么你的超时阈值设得太小。
• ENETUNREACH：网络不可达。路由断了，或者目标网络本身就不可及——可能是网络设备配置出错。
• ENOENT：文件/目录不存在。这个很常见——路径写错了、文件还没生成、挂载点没起来。
• EBADF / ENOTSOCK：无效的文件描述符或不是套接字。通常是文件或socket已经关闭了，但你还在操作它。
• EADDRNOTA VAIL：地址不可用。你试图绑定一个本机没有配置的IP地址，比如写了网卡上不存在的IP。
• EAFNOSUPPORT：地址族不支持。比如IPv6的配置跟IPv4混用了，或者说套接字类型和地址不匹配。
• EISCONN：已连接。调用 connect 时socket已经连上了，一般是因为重复调用导致的。

这些错误码在Linux/CentOS这类系统里极其常见。日志里一般会带着 Error: ... code: '...' 的格式，一眼就能辨认。

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

除了系统层面的错误，Node.js自己也会吐出一些运行时错误码。这些代码更多指向模块使用不当或环境约束：

• ERR_OUTOFMEMORY：内存不足。往往是大对象分配、内存泄漏、或者V8堆限制被触发了。
• ERR_STREAM_READ_NOT_IMPLEMENTED：自定义可读流忘了实现 _read() 方法。这是流实现的常见坑。
• ERR_TLS_RENEGOTIATION_FAILED：TLS重新协商失败。一般是客户端和服务器TLS版本或配置不兼容导致的。
• ERR_UNKNOWN_BUILTIN_MODULE：内部模块错误。说实话，这个通常不是用户代码的问题，更像是Node.js内部异常。
• ERR_STDOUT_CLOSE / ERR_STDERR_CLOSE：试图关闭 process.stdout 或 process.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" 不一致。

这类错误定位时，优先检查API的使用约束、模块系统配置，另外，Node.js版本也值得确认一下。

三 HTTP状态码与日志解读

HTTP层面的错误码是另一类重要信号。在Node.js应用（比如Express）里，状态码和响应体一起出现在日志中，能快速判断问题出在客户端还是服务端：

• 1xx：信息性响应——请求已收到，继续处理中。
• 2xx：成功——200 OK、201 Created这类。
• 3xx：重定向——301、302，需要客户端进一步操作。
• 4xx：客户端错误——400（请求格式错误）、401（未认证）、403（禁止访问）、404（找不到资源）。明显是请求本身有问题。
• 5xx：服务器错误——500（内部错误）、503（服务不可用）。这时候重点看服务端逻辑、数据库连接、第三方服务是否正常。

通过 res.status(code).send(...) 设置状态码是很常规的做法。日志中一般会同时出现状态码、堆栈和请求路径，能帮你快速判断：

四 快速排查步骤

上面讲了很多具体的错误码，但真正遇到问题时，怎么下手？其实有个通用流程：

1. 先定位错误码和上下文：这是第一步——拿到完整的错误堆栈、错误消息、发生时间、请求路径或目标地址、所在进程和线程信息。别只看个Code就猜。
2. 网络类错误（ECONNREFUSED / ECONNRESET / ETIMEDOUT / ENETUNREACH）：
   • 确认目标服务是否真的启动了，监听的是不是预期端口。用 ss -ltnp | grep :端口 或 netstat -tulpen | grep :端口 查一下。
   • 检查本机到目标主机的防火墙/安全组、路由和网络质量。如果网络环境确实不稳定，调整超时和重试策略也是常见解法。
3. 端口占用（EADDRINUSE）：
   • 查占用进程——lsof -i :端口 或 netstat -tulpen | grep :端口 拿到PID，kill -9 PID 干掉它，或者换个端口。
4. 权限类（EACCES）：
   • 尽量避免直接用root跑应用。为应用分配最小所需权限，必要时调整目录/文件权限，或用有权限的用户来运行。
5. 文件不存在（ENOENT）：
   • 确认配置、日志、上传目录是否存在并且可写。检查相对路径和工作目录是不是对的，容器或挂载卷有没有正确配置。
6. 运行时/模块错误（如ERR_OUTOFMEMORY、ERR_STREAM_READ_NOT_IMPLEMENTED）：
   • 检查代码路径是否触发了未实现的接口，或者资源没有被正确释放。监控内存占用和GC情况。升级Node.js版本，核对ESM/CommonJS配置的一致性。
7. HTTP状态码（4xx/5xx）：
   • 结合业务日志和中间件调用栈，定位路由、鉴权、参数校验以及上游依赖。5xx要重点排查：未捕获异常、数据库/缓存可用性、第三方服务健康度。

如果配合PM2这类进程管理工具以及监控告警，能进一步缩短恢复时间，降低再次出现的概率。