排查docker compose端口冲突需执行“查—判—清—防”四步闭环：先用lsof或netstat查宿主机端口占用，再结合docker ps与docker ps -a判别运行/已退出容器映射，接着docker compose down清理资源，最后通过动态端口分配、显式项目名和端口守护工具长效预防。
排查 docker compose 开发环境中的端口冲突与资源抢占，关键不是等报错再救火，而是建立“查—判—清—防”四步闭环。端口冲突本质是宿主机 tcp 端口被独占，只要同一 ip+端口组合已被某个进程（无论是否 docker）监听，新容器就无法绑定，直接失败并提示 bind for 0.0.0.0:x failed: port is already allocated。
快速定位哪个进程占了端口
别猜，直接查宿主机真实占用情况：
- 用
lsof -i :8080查指定端口（如 8080），输出含 PID、COMMAND、USER，一眼看出是本地 Node 进程、旧容器还是其他服务 - 用
sudo netstat -tulnp | grep :3306（加sudo才能看到其他用户进程），重点关注LISTEN状态行里的 PID/Program name - 对比
docker ps --format "table {{.Names}}\t{{.Ports}}"，确认当前运行容器实际映射了哪些宿主端口，避免误判“已停容器”还在占端口（其实 stopped 容器不占端口，但 exited 状态的容器若没删，其端口映射记录可能干扰判断）
识别 Docker 内部资源抢占真因
端口只是表象，背后常混杂多种抢占类型：
-
僵尸容器残留：执行
docker ps -a，重点看Exited状态容器——它们虽不运行，但若曾映射端口且未docker rm，Docker 有时会保留绑定（尤其在某些内核版本或 Docker 版本下） -
网络命名空间未释放：用
docker network inspect bridge查桥接网络中是否有异常容器条目；更彻底可docker network prune清理无用网络（注意仅限开发环境） -
Compose 多项目交叉覆盖：比如
project-a和project-b的docker-compose.yml都写了- "8000:8000"，启动顺序不同会导致后者失败；检查时需明确每个项目的COMPOSE_PROJECT_NAME是否隔离
一键清理与安全重启策略
排查后要快速恢复，但不能粗暴杀进程伤开发状态：
- 停掉冲突进程：若为本地开发服务（如
npm run dev），先Ctrl+C或查 PID 后kill -9 PID - 清理 Docker 资源：
docker compose down（当前目录）或docker compose -p myproj down（指定项目名），它会自动删容器、网络、临时卷；再补一句docker volume prune -f防止旧卷残留影响下次启动 - 避免重复启动：写个简单 wrapper 脚本，启动前先跑
lsof -i :${PORT} && echo "port ${PORT} occupied" && exit 1 || docker compose up -d
长期规避：从配置和流程上断根
靠每次手动查太累，开发环境应默认防御：
- 在
docker-compose.yml中，对非必须对外暴露的端口，改用- "8000"（只写容器端口），让 Docker 自动分配宿主端口，再用docker compose port service_name 8000查实际映射 - 为每个 Compose 项目显式设置
COMPOSE_PROJECT_NAME=project-a，避免默认用目录名导致命名冲突，也方便docker ps区分 - 接入
compose-port-guard这类工具：它能在docker compose up前自动扫描所有ports字段声明的宿主端口，冲突时直接报错并列出占用进程，省去人工 grep 步骤
