端口被占用怎么办？EADDRINUSE / Port already in use 全平台解决指南

现象：项目起不来，一行报错

Error: listen EADDRINUSE: address already in use :::3000

或英文形态：

Port 3000 is already in use

含义一句话：你要监听的端口已经被另一个进程占着。开发服务器、数据库、Docker 容器、上一个没退干净的 node 进程——都可能是占用者。

第一步：查出谁在占端口

macOS / Linux

lsof -ti:3000          # 只打印占用 3000 端口的进程 PID（脚本友好）
lsof -i:3000           # 人读版：PID、进程名、用户一目了然

Windows（PowerShell）

netstat -ano | findstr :3000     # 最后一列是 PID
tasklist /fi "PID eq 12345"      # 用 PID 查进程名

第二步：处理占用进程

情况 A：旧的开发服务器（最常见）

上次 Ctrl+C 没杀干净，或者终端关了进程还活着。直接结束它：

# macOS / Linux
kill -9 $(lsof -ti:3000)

# Windows（PowerShell）
taskkill /PID 12345 /F

判断依据：lsof -i:3000 显示的进程名是你自己的（node、vite、next-server 等）→ 放心杀。

情况 B：是别的服务在用这个端口

进程名不是你的项目（比如 postgres、mongod、另一个团队的服务）——别杀它，换自己的端口：

# 按框架改启动端口
next dev -p 3001          # Next.js
vite --port 3001          # Vite
npm start -- --port 3001  # 多数 CLI 支持

情况 C：Docker 容器映射了该端口

lsof 里进程名是 docker-proxy：

docker ps --filter "publish=3000"    # 找到容器
docker stop <容器名>                  # 停掉，或改 compose 里的端口映射

为什么要 kill -9？kill 不行吗？

先试普通 kill（发 SIGTERM，进程可以优雅退出），几秒后还在再 kill -9（SIGKILL，强杀）。开发场景的残留进程通常无所谓优雅，直接 -9 省事；生产数据库等有状态服务永远先用普通 kill。

预防：让端口冲突不再发生

1. 固定开发端口约定：团队约定 3000/3001/3002 分工，别抢；
2. 用 ports 变量：.env 里放 PORT=3001，配置引用变量而不是硬编码；
3. 退出走 Ctrl+C 而不是关终端：大多数 dev server 会随终端会话清理，但后台启动（&/nohup）的不会——后台起的进程要记 PID；
4. 端口 0 = 随机分配：写测试/脚本时监听 port 0 让系统分配空闲端口，从根上避开冲突。

高频追问

3000 端口在 Mac 上查出来是 ControlCenter？

macOS Monterey 起系统服务会占用若干端口（AirPlay 接收器常占 5000/7000）。ControlCenter 占 3000 属系统行为，别杀，改用自己的端口最省事。

杀完进程端口还是占用？

两种可能：①进程处于 TIME_WAIT 状态（一分钟内自动释放，等一下再试）；②有父进程拉起了新的子进程（Docker restart 策略、pm2、systemd）——找到管理者停它，而不是反复杀子进程。

EADDRINUSE 里 :::3000 的三个冒号是什么？

::: 是 IPv6 全地址 :: 加端口分隔符——你的服务试图监听 IPv6 的 3000 端口。与 IPv4 的 0.0.0.0:3000 是两个不同的监听，但多数程序（和这个报错场景）双栈共享，按占用处理即可。

一键脚本（放 alias 里）

# macOS/Linux：释放指定端口
freeport() { lsof -ti:"$1" | xargs kill -9 2>/dev/null && echo "port $1 freed" || echo "port $1 was free"; }
# 用法：freeport 3000

Windows 版（PowerShell profile）：

function freeport($p) { Get-NetTCPConnection -LocalPort $p -ErrorAction SilentlyContinue |
  ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } }

socket 三态：分层诊断

报错都叫「地址被占」但 socket 状态不同：LISTEN（进程在听——找到它并决策）、TIME_WAIT（没有进程——内核在重启后持有连接槽；应用开 SO_REUSEADDR 或等窗口——「服务为什么重启不起来」的经典）、绑了但没听（启动中的应用与你的探测赛跑）。ss -tlnp 一行看 LISTEN 及进程；ss -tan 看 TIME_WAIT 洪水——状态决定修法（杀/等 vs 配置）。Docker 加一层：docker-proxy 替容器持口——与已停未删容器的冲突是 prune 问题不是进程猎捕。

IPv4 / IPv6：两个套接字，同一条报错

:::3000 是 IPv6；0.0.0.0:3000 是 IPv4。多数 Node 框架双栈监听，只释放一边时另一边仍占。lsof -iTCP:3000 -sTCP:LISTEN 若出现两行（或 ss -tlnp | grep 3000 同时有 *:3000 与 [::]:3000），通常同一 PID，杀一次即可。若 A 只绑 IPv4、B 占了 IPv6，会出现「一边查询空闲、另一边 EADDRINUSE」。本地工具可显式绑 127.0.0.1，缩小冲突面。

Windows：被排除的端口段（Hyper-V / WSL）

Windows 上 netstat 可能看不到监听，但 bind 仍失败。Hyper-V、WSL 会预留动态端口段：

netsh interface ipv4 show excludedportrange protocol=tcp

若目标端口落在排除段里，杀进程也没用——换段外端口，或关掉占用该段的功能。这是 macOS ControlCenter 占 5000/7000 的 Windows 表亲。

框架自动换端口：静默开在「错的」服务上

Next.js / Vite / CRA 在 3000 被占时常自动跳到下一个空闲口，并在嘈杂终端里只打一行警告。结果：3000 上还是昨天的旧进程，你却在 3001 上怀疑「改动为何不生效」。习惯：每次启动核对 Local URL，或固定 PORT / -p 让冲突直接失败。需要拿回约定端口时，用上文的 freeport 一键释放。

SO_REUSEADDR 不是通行证

设置 SO_REUSEADDR（以及 Linux 的 SO_REUSEPORT）会让「杀完仍占」在重启间显得随机。Reuse 帮的是 TIME_WAIT 后快速重启，不能让两个无关进程共享同一 LISTEN。CI 里起了两份应用，第二份照样挂——修进程生命周期，别用 reuse 糊墙。

排查清单

1. lsof -ti:3000（Windows：netstat -ano | findstr :3000）拿到 PID
2. 看进程名：自己的残留 → 杀；别人的服务 → 换端口；docker-proxy → 停容器
3. 杀完还占：等 TIME_WAIT、找管理者，或查 Windows 排除段 / macOS ControlCenter
4. 报错带 :::port 时，确认 IPv4 与 IPv6 两侧都空
5. 长期方案：端口进 .env、后台进程记 PID、脚本用 port 0、框架固定端口失败即报

排查注记

处理占用者分三种情况，判断依据是 lsof 打出来的进程名：自己的残留进程放心杀，别人的服务（postgres、别组的服务）别杀、换自己的端口，docker-proxy 则要停容器——同一行报错对应三种完全不同的动作。「为什么要 kill -9」单独成节，先 SIGTERM 再 -9 的顺序是给有状态服务留优雅退出的机会。杀完仍占的两种可能（TIME_WAIT 一分钟内自动释放、父进程在拉新子进程）也按这个逻辑展开：不找到管理者，反复杀子进程没有意义。

本文出自 ToolVault 工具匣。开发部署相关工具：Dockerfile 生成器、docker run 转 compose、Linux 命令速查、HTTP 状态码速查。相关阅读：ECONNREFUSED 连接被拒绝排查、Docker 端口占用 port is already allocated。访问 首页 查看更多开发者工具。