1. 概述
在使用 Docker Compose 管理多容器 Docker 应用时，我们通常通过一个 docker-compose.yml 文件定义服务、网络和卷，从而通过一条命令快速启动整个环境。
然而，有时我们会遇到如下错误提示：
no configuration file provided: not found
这个错误通常出现在我们执行如 docker compose logs 或 docker compose ps 等命令时。其根本原因在于：Docker Compose 无法找到配置文件。
本文将带你了解这个错误的成因、如何复现，并提供多种解决方案，帮助你快速定位并解决问题。
2. 错误复现
默认情况下，docker compose 命令会从当前工作目录查找 docker-compose.yml 文件。如果找不到，就会报出上面的错误。
2.1 简单的 Docker Compose 项目
我们先创建一个项目目录：
$ mkdir example-project && cd example-project
然后创建一个简单的 docker-compose.yml 文件：
services:
web:
image: nginx:alpine
ports:
- "8080:80"
接着启动服务：
$ docker compose up -d
服务启动后，执行日志查看命令：
$ docker compose logs
输出如下日志片段，说明一切正常：
web-1 | /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
...
web-1 | 2025/08/08 03:03:17 [notice] 1#1: start worker process 32
web-1 | 2025/08/08 03:03:17 [notice] 1#1: start worker process 33
2.2 触发错误
现在我们退出当前目录：
$ cd ..
再次执行日志命令：
$ docker compose logs
输出错误信息：
no configuration file provided: not found
✅ 原因很明显：我们不在 docker-compose.yml 文件所在目录，Docker Compose 无法定位配置文件。
3. 常见解决方案
下面介绍几种解决该问题的常用方法。
3.1 在正确目录下执行命令
最简单的方式就是确保你在 docker-compose.yml 所在目录中执行命令：
$ cd example-project && docker compose logs
⚠️ 适用于日常开发或调试，但不适合自动化脚本。
3.2 使用 --project-directory 参数指定项目目录
如果你不想切换目录，可以使用 --project-directory 参数告诉 Docker Compose 配置文件所在位置：
$ docker compose --project-directory ./example-project logs
✅ 适用于以下场景：
- 编写自动化脚本或 CI/CD 任务
- 从父目录或外部目录执行命令
- 管理多个 Compose 项目
⚠️ 该参数会将指定目录作为项目根目录，Docker Compose 会在该目录中查找 docker-compose.yml。
3.3 使用 -f 参数显式指定配置文件路径
如果你希望从其他目录运行命令，也可以使用 -f 参数显式指定配置文件路径：
$ docker compose -f example-project/docker-compose.yml logs
✅ 适用于：
- 从任意目录执行命令
- CI/CD 流水线脚本中使用
- 合并多个配置文件（如 base + override）
例如合并多个配置文件：
$ docker compose -f docker-compose.yml -f docker-compose.override.yml logs
⚠️ 多个配置文件按顺序合并，后面的文件可以覆盖前面的内容。
3.4 设置 COMPOSE_FILE 环境变量
你也可以通过设置环境变量来指定配置文件路径：
$ export COMPOSE_FILE=example-project/docker-compose.yml
之后即使你在上级目录执行命令，也能正常获取日志：
$ cd .. && docker compose logs
✅ 适用于需要连续执行多个命令的场景，避免重复指定 -f。
4. 验证配置文件是否可访问
如果你不确定 Docker Compose 是否成功加载了配置文件，可以使用以下命令验证：
$ docker compose config
如果配置文件存在且格式正确，它会输出解析后的完整配置内容，例如：
name: example-project
services:
web:
image: nginx:alpine
networks:
default: null
ports:
- mode: ingress
target: 80
published: "8080"
protocol: tcp
networks:
default:
name: example-project_default
如果提示 no configuration file provided: not found，说明配置文件路径不正确，需要检查当前目录或使用 -f 或 --project-directory 参数重新指定。
5. 总结
遇到 no configuration file provided: not found 错误时，核心思路是：
✅ 确保 Docker Compose 能找到 docker-compose.yml 文件
你有以下几种解决方式可选：
| 方法 | 命令示例 | 适用场景 |
|---|---|---|
| 切换到项目目录执行 | cd example-project && docker compose logs |
日常调试 |
使用 --project-directory |
docker compose --project-directory ./example-project logs |
自动化脚本、避免切换目录 |
使用 -f 参数 |
docker compose -f example-project/docker-compose.yml logs |
指定具体配置文件路径 |
设置 COMPOSE_FILE 环境变量 |
export COMPOSE_FILE=example-project/docker-compose.yml |
多命令连续执行 |
掌握这些方法后，你就可以灵活应对 Docker Compose 的配置路径问题，不再踩坑。