VSCode 调试 Node.js 端口占用报错 EADDRINUSE 怎么解决

VSCode 调试 Node.js 时报 EADDRINUSE，本质是目标端口被其他进程占用。最直接的解决方式是查找占用该端口的进程 ID 并终止它，若无法终止则修改调试配置中的端口号。

先说结论：优先排查占用端口的进程并清理，若无法清理则修改本地监听端口配置。

先确认：使用 netstat 或 lsof 命令定位占用端口的进程 PID
先处理：通过 taskkill 或 kill 命令终止占用进程（优先普通终止，无效再强制）
再验证：重新启动调试会话，确认报错消失且服务正常监听

快速排查命令

根据操作系统不同，使用以下命令快速查找并释放端口（以 3000 端口为例）：

Windows：

查找进程：netstat -ano | findstr :3000
终止进程：taskkill /PID 12345 /F（将 12345 替换为实际 PID）

macOS / Linux：

查找进程：lsof -i :3000
终止进程：kill 12345（优先尝试普通终止，若无效再使用 kill -9 12345）

注意：macOS/Linux 若提示权限不足，需在命令前加 sudo。

为什么会这样

EADDRINUSE 错误表示地址已被使用，通常是因为 Node.js 服务上次未正常关闭，导致进程仍在后台运行并占用端口。此外，VSCode 的调试端口配置与应用程序实际监听端口不一致，或者本地其他服务（如 Live Server）占用了相同端口，也会触发此报错。

分步处理与配置修改

1. 查找占用进程

VSCode 调试 Node.js 端口占用报错 EADDRINUSE 怎么解决

在终端运行上述命令，记录输出结果中的 PID 列。

2. 终止进程

使用对应系统的终止命令释放端口。若提示权限不足，Windows 需管理员运行命令提示符，macOS/Linux 需加 sudo。

3. 修改调试配置（可选）

若无法终止进程，可在项目根目录 .vscode/launch.json 中修改配置。以下是典型配置示例，可通过 env 变量覆盖端口：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug Node.js",
            "program": "${workspaceFolder}/app.js",
            "env": {
                "PORT": "3001"
            }
        }
    ]
}

4. 修改代码或启动脚本（可选）

确保代码中监听端口支持环境变量控制，避免硬编码：

const port = process.env.PORT || 3000;
app.listen(port, () => {
    console.log(`Server running on port ${port}`);
});

若使用 npm 启动，也可在 package.json 的 scripts 中指定端口：

"scripts": {
    "start": "PORT=3001 node app.js"
}

5. 检查扩展配置

若是 Live Server 等扩展冲突，需在 VSCode 设置中搜索 liveServer.settings.port 进行修改，而非修改 launch.json。

怎么验证是否生效

再次运行查找端口的命令，确认无输出结果表示端口已空闲。启动 VSCode 调试，观察调试控制台是否不再出现 EADDRINUSE 错误，且浏览器或客户端能正常访问服务。

常见坑

1. 配置错位：launch.json 中的 port 仅控制调试器，若应用代码硬编码了端口，需同时修改代码或通过环境变量覆盖。

2. IPv4 与 IPv6 差异：某些服务绑定 ::1 而新进程绑定 127.0.0.1，看似不同实则端口共享，仍可能冲突。

3. 残留进程：使用 nodemon 等工具时，异常退出可能导致旧进程未彻底关闭，需手动清理所有 node 相关进程。

4. 强制杀进程风险：尽量避免直接使用 kill -9，优先使用 kill 让进程有机会清理资源，防止数据丢失。