EADDRINUSE 端口被占用怎么解决？查进程、杀进程、换端口（3000/8080）

启动项目时报 Error: listen EADDRINUSE: address already in use :::3000，意思很简单：3000 端口已经被另一个进程占着了——通常是你上一个 npm run dev 没真正关掉，还在后台跑。

两条路解决：找到并杀掉占端口的进程，或者换一个端口。下面给两个系统的真实命令。

先确认是哪个端口

报错里 :::3000 或 :8080 那个数字就是被占的端口。常见的是 3000（Next.js / CRA）、5173（Vite）、8080、5000。

方法一：杀掉占端口的进程（macOS / Linux）

# 查谁占了 3000 端口
lsof -i :3000
# 直接拿到 PID 并杀掉
lsof -ti:3000 | xargs kill -9

kill -9 是强制结束，先用 lsof -i :3000 看清是不是自己的 dev 进程，别误杀别的服务。

方法二：杀掉占端口的进程（Windows）

# 查 PID（最后一列就是 PID）
netstat -ano | findstr :3000
# 按 PID 结束进程
taskkill /PID <上面查到的PID> /F

方法三：不杀进程，直接换端口

不想杀进程，换个端口起最省事：

# Next.js / 通用：用 PORT 环境变量
PORT=3001 npm run dev
# Next.js 也可以
npm run dev -- -p 3001
# Vite
npm run dev -- --port 3001

方法四：用 kill-port 一行搞定（跨平台）

npx kill-port 3000

不用记 lsof / netstat，npx kill-port 跨平台直接释放端口。

为什么会反复发生

• 关终端时进程没被一起结束（尤其后台 & 启动的）；
• 用 Ctrl+Z 挂起而不是 Ctrl+C 结束；
• 同一个项目开了两个终端各起了一次 dev。

养成用 Ctrl+C 正常结束、一个项目只起一个 dev 的习惯，就能少踩。

让 Codex 辅助

我启动项目报 EADDRINUSE address already in use :::3000。
请给出我当前系统（macOS/Windows）下查占用进程和释放端口的命令，
杀进程前先告诉我怎么确认这个进程确实是我自己的 dev，别误杀。

风险提醒

• kill -9 / taskkill /F 是强制结束，杀错会中断别的服务（数据库、其他项目）。先确认 PID 再杀。
• 公司或服务器上的端口占用，可能是受管服务，别擅自杀，先确认归属和授权。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关报错排查

同一套排查思路的常见报错，建议一起看：

• npm run dev 能跑但 build 失败
• Cannot find module 报错怎么解决
• npm command not found 怎么解决

免责声明

本文命令对应 macOS / Linux / Windows 的标准行为，供学习和排查参考；在客户服务器或受管设备上操作端口和进程，需明确授权并人工复核。