遇到 docker-compose 运行报错时，先检查 Docker 服务是否正常运行，再验证配置文件语法，最后查看具体服务日志定位问题。

命令速用版

以下是快速排查时可执行的命令，按顺序尝试：

systemctl status docker
docker-compose config
docker-compose logs <service_name>
lsof -i :<port>
docker-compose up -d

如果命令提示找不到 docker-compose，尝试使用 docker compose（V2 版本语法）。

为什么会这样

docker-compose up -d 执行时会在后台完成多个步骤：解析配置文件、检查镜像、创建网络、启动容器。任何一个环节出问题都会导致命令失败。常见情况包括 Docker 服务本身没运行、配置文件缩进或拼写有误、宿主机端口被其他进程占用、镜像无法从仓库拉取、挂载目录权限不足等。

YAML 格式对空格非常敏感，使用 Tab 键缩进或冒号后缺少空格都会导致解析失败。端口冲突则是因为同一时间一个端口只能被一个进程绑定。镜像拉取失败通常与网络环境或仓库认证有关。

分步处理

第一步：检查 Docker 服务状态

执行 systemctl status docker 查看服务是否 active。如果显示 inactive 或 failed，执行 sudo systemctl start docker 启动服务。Windows 用户需确认 Docker Desktop 是否运行，任务栏图标应为绿色状态。

第二步：验证配置文件语法

在同级目录下执行 docker-compose config，如果输出配置内容说明语法正确，如果报错则根据提示修正缩进或键名。确保使用空格而非 Tab 键，服务名字段顶格书写，子字段统一用 2 个空格缩进。

第三步：检查端口占用

如果报错提示 port is already allocated，使用 lsof -i :8080 或 netstat -tulnp | grep :8080 查看占用进程。可修改 docker-compose.yml 中的端口映射，或终止占用进程后重试。

第四步：处理镜像拉取失败

报错 pull access denied 时，确认镜像名称正确，私有仓库需先执行 docker login 登录。可手动执行 docker pull <image_name> 测试拉取是否正常，网络受限时可配置国内镜像源。

第五步：检查挂载目录权限

卷挂载失败通常因为宿主机目录不存在或权限不足。执行 mkdir -p ./data 创建目录，用 chmod 设置适当权限。生产环境权限不应过于宽松，777 仅用于测试。

怎么验证是否生效

修复后执行 docker-compose up -d 重新启动，然后用 docker-compose ps 查看容器状态，应显示 Up 而非 Exit 或 Restarting。执行 docker-compose logs -f <service_name> 查看实时日志，确认无报错信息。访问服务对应端口，验证应用是否可正常响应。

如果容器仍立即退出，重点查看日志中的 exec format error（架构不匹配）、no such file or directory（入口脚本路径错）、Permission denied（权限问题）等关键错误信息。

常见坑

docker-compose 与 docker compose 是两个版本，V1 使用连字符，V2 使用空格分隔，同时安装可能导致命令解析失败。depends_on 只控制启动顺序，不等待依赖服务就绪，数据库类服务需配合 healthcheck 或应用层重试。

环境变量在 compose 文件中要写成 KEY: value 或 - KEY=value 格式，不能混用。端口映射必须用字符串数组格式，如 ["8080:80"]，无引号会解析失败。服务间网络互通直接用服务名当 hostname，无需配置 IP。

非 root 用户操作 Docker 需加入 docker 用户组，否则报 permission denied。执行 sudo usermod -aG docker $USER 后需重新登录或执行 newgrp docker 使权限生效。

参考来源

• docker compose 出错怎么办，发布时间 2023 年 4 月 19 日
• 解决 Docker Compose 无法执行问题的常见方法，发布于 2024 年 1 月 18 日
• 5 种常见的 Docker Compose 错误，资料日期 2022 年 1 月 7 日