16 个 Node.js 常见错误速查与修复指南
Heap OOM、ECONNRESET、EADDRINUSE……本文汇总 16 个 Node.js 高频错误的成因与修复方案，附生产环境错误处理实践，收藏级速查手册。
Node.js 高频错误分四类：内存类（Heap OOM→查泄漏或调 --max-old-space-size）、网络类（ECONNRESET/ETIMEDOUT→重试与超时配置）、端口类（EADDRINUSE→换端口或杀占用进程）、文件类（ENOENT→检查路径与权限）。生产环境靠统一错误处理与监控告警兜底。
内存类
1. Heap Out of Memory（JavaScript heap out of memory）
V8 堆超限崩溃。排查：是否内存泄漏（见本系列《内存泄漏防治指南》）；短期缓解：node --max-old-space-size=4096 app.js。容器部署注意该值要小于容器内存上限。
网络类
2. ECONNRESET：对端强制断开。常见于：下游服务重启、代理空闲超时。处理：请求库配置重试（指数退避），服务端检查 keep-alive 超时与代理超时的匹配。
3. ENOTFOUND：DNS 解析失败——域名拼错、DNS 配置错误、或目标域名确实不存在。
4. ETIMEDOUT：连接超时——网络不通、防火墙拦截、目标过载。所有外部调用必须设超时（axios 的 timeout、fetch 的 AbortSignal.timeout）。
5. ECONNREFUSED：连接被拒绝——目标端口没有服务在听。检查：服务是否启动、端口是否正确、容器端口映射。
8. ECONNABORTED：客户端中途放弃（浏览器取消请求）。服务端应把它当正常事件处理而非错误告警。
9. EHOSTUNREACH / 10. EAI_AGAIN：路由不可达 / DNS 临时失败——多为基础设施层抖动，重试机制是标准答案。
端口与地址类
6. EADDRINUSE：端口被占用。lsof -i :3000 找到占用进程；开发期常见于上一个进程没退干净。生产上用进程管理器避免双实例。
7. EADDRNOTAVAIL：绑定了一个本机不存在的 IP（服务器换 IP 后配置没更新）。
文件系统类
11. ENOENT：文件/目录不存在——相对路径陷阱（工作目录变了路径就错），用 path.join(__dirname, ...) 锚定。
12. EISDIR / 13. ENOTDIR：把目录当文件读 / 路径中间某段不是目录——路径拼接逻辑检查。
14. EACCES / 16. EPERM：权限不足。别用 root 跑应用掩盖问题——给应用用户精确授权才是正解。
15. EEXIST：创建已存在的文件/目录——mkdir 加 { recursive: true }，文件操作先判断存在性。
生产环境的错误治理
// 全局兜底：未捕获异常与未处理 Promise 拒绝
process.on('uncaughtException', (err) => {
logger.fatal({ err }, '未捕获异常，进程即将退出');
process.exit(1); // 记录后退出，让进程管理器重启——状态未知的进程不可信
});
process.on('unhandledRejection', (reason) => {
logger.error({ reason }, '未处理的 Promise 拒绝');
});
常见问题（FAQ）
Q：遇到陌生错误码怎么查？
Node.js 错误码体系在官方文档有完整列表（搜索 "Node.js errors"）。errno 体系源自 Unix——理解 syscall 层的语义，错误码就不再神秘。
Q：uncaughtException 里该做什么？
只做两件事：记录日志（同步方式，异步可能完不成）、优雅退出。不要在里面"恢复继续跑"——未捕获异常后的进程状态不可信。
Q：如何减少网络类错误的影响？
三件套：所有外部调用设超时、失败重试带指数退避与熔断、关键路径有降级方案。配合监控把网络错误率纳入 SLI。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
