启动服务时控制台扔出一行Error: listen EADDRINUSE: address already in use :::3000,进程随即退出。这不是代码写错,3000端口此刻被别的进程占着,Node.js的server.listen()拿不到这个地址,直接抛EADDRINUSE。同一台机器上开两个终端跑npm run dev、上次的服务没退干净、cluster里主进程和worker都调了listen,都会撞上这一句。
Error: listen EADDRINUSE: address already in use :::3000 at Server.setupListenHandle [as _listen2] (node:net:1817:16)
这个报错在开发机上遇到过不止一次,多数时候跟代码无关,纯粹是端口没腾出来。
1、先把占着端口的进程揪出来
Linux和macOS上最省事的是lsof -i :3000,输出里COMMAND、PID、TYPE、NAME几列一眼能看出是谁在LISTEN。列名被截断就用lsof +c0 -i :3000打全进程名。ss比netstat快,还带进程号:
lsof -nP -iTCP:3000 -sTCP:LISTEN ss -ltnp | grep :3000
ss那行的users:(("node",pid=54321,fd=22))就是目标。拿到PID先发SIGTERM让进程自己收尾,kill 54321,不听话再kill -9 54321。fuser 3000/tcp能一次打印PID,fuser -k 3000/tcp直接结束占用者。Windows下换成netstat -ano | findstr :3000找LISTENING那行的PID再taskkill /PID 54321 /F,这一步属于通用的端口占用排查,跟Node.js本身没多大关系。
2、对上症状再决定改哪一处
别一上来就杀进程,五种成因的处理方向完全不同。
终端面板关了、按了Ctrl+Z而不是Ctrl+C,node进程被init收养继续跑,端口一直开着,这种在VS Code集成终端里最常见。nodemon、tsx watch、pm2这类监视器重载时碰到崩溃竞态,也会留下孤儿进程,实测重启后几秒内又复现,八成就是它留下的孤儿进程。cluster代码里主进程和worker都写了listen(3000),第二个必然报EADDRINUSE。Docker把宿主端口已经-p发布给另一个容器,容器内看不到宿主的名字空间,ss里查不到,要docker ps --format '{{.Names}} {{.Ports}}'单独看。CI里并行测试worker写死同一个端口,谁先起谁占。
之前接手过一台CI机器,两个测试worker抢同一个3000端口,隔一次挂一次,日志翻半天才发现是并行度调高之后才出现的。见过更隐蔽的一次,服务监听在40000端口,落在Linux临时端口区间里,几十次启动才撞上一回。
还有个macOS上最容易撞的:AirPlay Receiver默认占着5000和7000,本地起个服务刚好用这两个端口,报的也是EADDRINUSE,跟Node.js版本没关系。
3、TIME_WAIT和SO_REUSEADDR别乱调
主动关闭连接的一方要把套接字留在TIME_WAIT里等两倍MSL,Linux默认约60秒,Windows约240秒。很多资料会让人去改tcp_tw_recycle,这个参数在Linux 4.12就因为NAT环境下出问题被移除了,别再照抄。Node.js对server.listen()默认已经设了SO_REUSEADDR,正常重启不会卡在TIME_WAIT;用原生net.createServer()可以显式写reuseAddr:
const net = require('net');
const server = net.createServer();
server.listen({ port: 3000, reuseAddr: true });
要是lsof和ss都查不到占用者,再去看ss -tan | grep 3000有没有TIME-WAIT条目。Python的socket默认不设SO_REUSEADDR,Go的net.Listen默认设了,跨语言混部的时候这一层差异经常背锅。
4、让端口不再写死
热重载场景把重启放进server.close()的回调里,等旧server真正关掉再listen,比裸kill稳:
server.close(() => {
startNewServer();
});
const s2 = app.listen(0);
console.log(s2.address().port);
测试套件里更干脆的做法是listen(0),让操作系统随手分一个空闲端口,再用server.address().port读回实际值,并行跑多少个worker都不会撞。IPv6那串:::3000也值得留意,localhost有时解析到::1、有时到127.0.0.1,绑定地址写死一边,另一边访问就是ECONNREFUSED,那是另一个报错,别跟EADDRINUSE混着查。服务端口落在net.ipv4.ip_local_port_range默认的32768到60999里,还可能被出站连接临时抢走,用net.ipv4.ip_local_reserved_ports把端口预留出来,或者干脆把服务挪到32768以下。
Node 18.20.0、20.19.0、22.12.0、22.14.0,这些版本上listen对端口冲突的处理一致,没有哪个版本会自动挑一个别的端口;nodemon 3.1.0、3.1.7,也只是把重启时机挪了挪,抢端口的根子还在进程没退干净。2024年、2025年到2026年这几轮LTS里,EADDRINUSE的报错文本都没变过,排错顺序也不用作调整,数据截至2026年11月。
把端口写死在多个项目里,迟早会撞上;按上面的顺序查一遍,基本能定位到是谁占着。