如何解决Node.js中listen EADDRINUSE端口占用错误？

问题详情 #

运行以下Node.js Web服务代码：

const port = 3000;
app.get('/hello', (req, res, next) => {
    res.send('Hello, World!');
});
app.listen(port, () => {
    console.log('listening to port', port);
}); 

首次启动正常，但后续执行node index.js时触发错误：

node:events:489
  throw er; // Unhandled 'error' event
  ^
Error: listen EADDRINUSE: address already in use :::3000

已尝试npx kill-port 3000及更换多个端口，问题仍存在，需其他解决方案。

可行解决方案 #

• 手动查杀占用端口的进程
  部分情况下kill-port无法彻底终止进程，需手动定位并强制结束：

  • Windows：

    netstat -ano | findstr :3000
    taskkill /F /PID [查到的进程ID]
    

  • macOS/Linux：

    lsof -i :3000
    kill -9 [查到的进程ID]
    

• 排查未释放的异步资源
  若服务存在数据库连接、WebSocket等持久化资源，关闭时未正确释放会导致进程残留：
  添加进程退出监听，确保资源被清理：

  process.on('SIGINT', () => {
    // 示例：关闭数据库连接等资源
    // db.close();
    console.log('服务正在关闭...');
    process.exit(0);
  });
  

• 检查系统或第三方程序端口占用
  杀毒软件、防火墙、后台服务（如代理、数据库）可能占用目标端口：

  • Windows：使用TCPView工具查看端口占用详情
  • macOS/Linux：执行ss -tulpn | grep :3000查看占用端口的程序

• 实现端口自动检测与切换
  启动服务前先检测端口可用性，自动切换至未占用端口：

  const net = require('net');
  const targetPort = 3000;
  
  const checkPort = (port) => {
    return new Promise((resolve) => {
      const server = net.createServer();
      server.once('error', () => resolve(false));
      server.once('listening', () => {
        server.close();
        resolve(true);
      });
      server.listen(port);
    });
  };
  
  const startServer = async () => {
    let port = targetPort;
    while (!(await checkPort(port))) {
      port++;
      console.log(`端口${port-1}被占用，尝试端口${port}`);
    }
    app.listen(port, () => console.log(`服务监听端口${port}`));
  };
  
  startServer();
  

• 清理Node.js僵尸进程
  执行以下命令列出所有Node.js进程，清理无关的僵尸进程：

  # macOS/Linux
  ps aux | grep node
  kill -9 [僵尸进程PID]
  
  # Windows
  tasklist | findstr node.exe
  taskkill /F /PID [进程ID]
  

内容的提问来源于stack exchange，提问作者Amrmsmb