Node.js 在测试或监听模式下 server.listen 报 EADDRINUSE

症状

启动服务器报 EADDRINUSE，单独通过的测试一起跑时失败。这种模式指向端口复用：残留的服务器、并行测试绑定同一固定端口，或监听模式在上一个套接字释放前就重启。硬编码端口让每次运行都争抢同一资源。

诊断

用 ss -ltnp 找出占用端口的进程；测试改用 listen(0) 让系统分配空闲端口；在 teardown 中关闭服务器。

ss -ltnp | grep :3000

根因

端口已被占用，来源可能是残留服务器、并行测试共用固定端口，或重启时上一个实例尚未释放。

修复

在 teardown 中关闭服务器释放端口；测试绑定端口 0 并从地址读取所分配端口；监听模式避免固定端口。让各次运行得以并存而不争抢单一端口。

验证

跑完整测试套件确认无 EADDRINUSE，并在结束后检查端口已空闲。一起运行干净且不残留监听者才算修好。

常见陷阱

用固定端口并在测试间 sleep 只能掩盖竞态；应改用动态端口与显式关闭。