RUNBOOK / Node.js
Node.js EADDRINUSE：端口已被占用的安全定位与恢复
Node 服务启动时出现 listen EADDRINUSE: address already in use，或因已有进程监听端口而无法绑定。
故障现象与判断依据
最可能原因
Node.js 官方错误说明将 EADDRINUSE 定义为尝试绑定一个已经在使用中的服务器地址；先确认监听者和启动方式，再决定是否停止明确的旧进程。
LOGError: listen EADDRINUSE: address already in use :::3000
at Server.setupListenHandle [as _listen2] (node:net:...)
code: 'EADDRINUSE'安全诊断
以下命令用于读取状态、验证解析或复现请求；先确认目标主机、权限与影响范围。命令中的占位符必须替换为当前环境的实际值。
READ / VERIFYlsof -nP -iTCP:<port> -sTCP:LISTEN
# Linux 上也可用：
ss -ltnp '( sport = :<port> )'
systemctl status <unit> --no-pager推荐修复步骤
- 1执行 lsof -nP -iTCP:<port> -sTCP:LISTEN 或 ss -ltnp，记录该端口的 PID、进程名和监听地址。
- 2检查 systemctl status <unit>、容器编排或进程管理器，确认是否存在同一服务的重复启动。
- 3仅在已确认属于旧实例或错误进程时，按该服务的受控停止方式释放端口；不要按端口号盲目 kill 或改为随机端口。
验证、限制与回滚
修复后的验证
再次启动服务后，监听检查只显示预期进程；应用健康检查返回预期状态。
风险提示与回滚
不要以关闭证书校验、删除全部缓存、无限重试、关闭防火墙或放宽到 chmod 777 来替代根因定位。任何配置变更前先保留原文件和校验结果；若验证失败，恢复该备份并重新采集日志。
可信来源与适用边界
参考来源Errors | Node.js ↗
EADDRINUSE means an attempt to bind a server address already in use 此页将环境级案例与本 Runbook 的检查步骤分开呈现，不能把示例日志当作当前服务器的真实事件。