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

Node.js服务启动时出现EADDRINUSE错误，本质是目标端口已经被其他进程占用，导致当前服务无法绑定该端口。不同操作系统的进程管理方式不同，排查和释放端口占用的操作也有区别，下面分别介绍不同系统下的解决方案。

Windows系统下解决EADDRINUSE错误

第一步：查找占用端口的进程

打开命令提示符或者PowerShell，执行以下命令查询指定端口的占用情况，将8080替换为实际报错的端口号：

netstat -ano | findstr :8080

命令执行后会返回类似如下的结果，最后一列的数字就是占用该端口的进程PID：

TCP    0.0.0.0:8080           0.0.0.0:0              LISTENING       12345

第二步：释放占用端口的进程

拿到PID之后，执行以下命令强制结束该进程：

taskkill /PID 12345 /F

如果提示操作成功，重新启动Node.js服务即可正常使用8080端口。

macOS和Linux系统下解决EADDRINUSE错误

第一步：查找占用端口的进程

打开终端，执行以下命令查询端口占用情况，同样替换8080为实际端口：

lsof -i :8080

命令返回结果中，PID列就是占用端口的进程ID，COMMAND列是进程名称：

COMMAND   PID   USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
node    12345  admin   12u  IPv6  0x1234567890abcdef      0t0  TCP *:8080 (LISTEN)

第二步：释放占用端口的进程

执行以下命令结束对应进程，替换12345为实际的PID：

kill -9 12345

如果是普通用户权限无法结束进程，可以在命令前加sudo提升权限：

sudo kill -9 12345

Node.js代码层面避免EADDRINUSE错误

除了手动释放端口，我们还可以在代码中添加端口占用的处理逻辑，当目标端口被占用时自动切换到其他可用端口。

自动切换可用端口的实现

以下代码会在启动时检测端口是否可用，如果被占用则自动递增端口号直到找到可用端口：

const net = require('net');
const http = require('http');

// 检测端口是否可用的函数
function checkPortAvailable(port) {
  return new Promise((resolve, reject) => {
    const server = net.createServer();
    // 监听端口成功则端口可用
    server.once('listening', () => {
      server.close();
      resolve(true);
    });
    // 监听失败则端口被占用
    server.once('error', (err) => {
      if (err.code === 'EADDRINUSE') {
        resolve(false);
      } else {
        reject(err);
      }
    });
    server.listen(port);
  });
}

// 查找可用端口的函数
async function findAvailablePort(startPort) {
  let port = startPort;
  while (true) {
    const isAvailable = await checkPortAvailable(port);
    if (isAvailable) {
      return port;
    }
    port++;
  }
}

// 启动服务
async function startServer() {
  const defaultPort = 8080;
  const availablePort = await findAvailablePort(defaultPort);
  const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Server is running on port ' + availablePort);
  });
  server.listen(availablePort, () => {
    console.log('Server started on port ' + availablePort);
  });
}

startServer();

捕获EADDRINUSE错误并处理

也可以在服务启动失败时捕获错误，提示用户端口被占用：

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World');
});

const port = 8080;
server.listen(port, () => {
  console.log('Server running on port ' + port);
});

// 捕获端口占用错误
server.on('error', (err) => {
  if (err.code === 'EADDRINUSE') {
    console.error('Port ' + port + ' is already in use, please change the port or stop the process using it');
  } else {
    console.error('Server error:', err);
  }
});

常见注意事项

• 排查端口占用时，要确保查询的端口号和报错信息中的端口号一致，避免操作错误进程。
• 结束进程前确认该进程不是系统关键进程，避免影响系统正常运行。
• 如果是Docker等容器环境内的端口占用，需要先进入容器内部再执行排查命令，或者检查宿主机的端口映射配置。
• 开发过程中如果频繁重启服务出现EADDRINUSE，可能是进程没有正常退出，可以在代码退出时主动关闭服务监听。

Node.jsEADDRINUSE端口占用跨平台修改时间：2026-06-21 20:24:33