← 中文资源

简体中文版本

Node.js EADDRINUSE — 端口已被占用

诊断并解决 Node.js 因端口被其他进程占用或旧实例未退出而无法绑定端口的 EADDRINUSE 错误。

阅读英文原文

症状

进程启动时立即退出,报错 Error: listen EADDRINUSE: address already in use :::3000;开发服务器重启失败,但旧进程仍在提供服务;请求被旧版本处理。

诊断

lsof -i :3000
# Windows
netstat -ano | findstr :3000

输出会显示占用端口的 PID 和命令。先用 ps -p <pid> -o pid,ppid,etime,command 确认它是你的进程,再决定是否停止;不要盲目杀死共享机器上的未知进程。如果同一端口存在多个监听器或 IPv4/IPv6 双栈冲突,ss -ltnp 'sport = :3000' 可以显示绑定情况。

根因

操作系统对同一地址与端口只允许一个监听者。新进程请求绑定旧进程仍持有的套接字,内核以 EADDRINUSE 拒绝。

修复

如果占用者是你的旧进程,先发送 SIGTERM 让它优雅退出;Windows 使用 taskkill /PID <pid>,/F 只作为最后手段。watch 模式应等待旧进程退出后再启动新进程。开发环境应让端口可配置,并在冲突时给出清晰错误,而不是静默换端口导致你测试了错误实例。

验证

  • 只有一个进程监听预期端口。
  • 响应来自新构建(检查版本号或新的启动日志)。
  • 重启开发服务器无需手动清理即可成功。
  • 关机后没有残留子进程。

如果占用端口的不属于你,换一个端口或与所有者协调,不要直接终止。