docker compose服务启动失败常因端口冲突，需先执行docker ps --format "table {{.names}}\t{{.ports}}\t{{.status}}"和docker-compose ps查映射端口，再用lsof或netstat定位占用进程，最后核对compose文件ports配置并清理残留容器。
服务编排中端口冲突是容器启动失败的高频原因，尤其在 Docker Compose 多服务协同场景下——一个服务占着 8080，另一个也想用，Docker 就直接拒绝启动。关键不是“能不能跑”，而是“谁先占了路”。
看一眼所有正在映射端口的容器
运行以下命令，快速摸清当前宿主机上哪些容器正在占用哪些端口：
-
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"—— 列出所有运行中容器的名称、端口映射和状态 -
docker-compose ps（在项目目录下）—— 显示当前 compose 项目里各服务的状态和端口绑定情况 - 注意：已停止但未删除的容器（
docker ps -a可见）有时仍会残留端口绑定，尤其是用docker-compose down未加--volumes时
查清楚宿主机端口到底被谁吃了
如果发现某个端口（比如 3000）在 compose 文件里写了，但启动报错“port is already allocated”，就说明它真被占了：
- Linux/macOS：
sudo lsof -i :3000或sudo netstat -tulnp | grep :3000 - Windows（PowerShell）：
Get-NetTCPConnection -LocalPort 3000 | Format-List * - 输出里会显示 PID 和进程名。如果是
docker-proxy，说明是另一个 Docker 容器；如果是node、python或nginx，那就是宿主机原生服务在抢道
对照 compose 文件逐项核对端口配置
很多冲突其实来自配置疏忽，不是技术问题，是人眼漏看了：
- 检查
ports:是否写成"8080:80"这种固定映射 —— 多个项目共存时极易撞车 - 确认不同服务之间没有重复声明同一宿主机端口（例如两个 service 都写了
- "8080:80"） - 留意环境变量写法：
- "${API_PORT:-3000}:3000"比硬编码更安全，也方便多环境切换 - 特别注意：Docker Compose 默认使用桥接网络，所有服务共享宿主机端口空间，不存在“互相隔离”这回事
临时绕过 + 长期预防两手抓
紧急情况下先让服务跑起来，再逐步理清根源：
- 临时改端口：把
8080:80改成8081:80，验证是否真为端口问题 - 清理残留容器：
docker-compose down && docker rm -f $(docker ps -aq)（慎用，确认无重要数据） - 长期建议：团队约定端口分配表（如前端 3000、后端 8000、数据库 5432），并在 CI/CD 中加入端口可用性检查脚本
- 进阶做法：用
network_mode: "host"规避端口映射（仅限开发调试），或改用用户自定义网络 + 内部 DNS 通信，减少对外暴露端口数量
