docker compose up 命令会按照以下顺序查找配置文件,直到找到为止:
📍 默认查找顺序(从高到低优先级)
1. 命令行指定的配置文件(最高优先级)
# 指定单个文件
docker compose -f docker-compose.yml up
# 指定多个文件(按顺序合并)
docker compose -f docker-compose.yml -f docker-compose.prod.yml up
2. 当前目录的默认文件
在当前工作目录中按以下顺序查找:
compose.yaml (首选)
compose.yml (次选)
docker-compose.yaml (备用)
docker-compose.yml (传统格式)
3. 环境变量指定
# 通过环境变量指定配置文件
export COMPOSE_FILE=docker-compose.prod.yml
docker compose up
4. 项目目录查找
如果通过 -p 指定了项目名称,会在项目目录中查找上述文件。
🔍 详细查找规则
规则详解:
# 假设当前目录是 /app
cd /app
# 查找顺序:
# 1. 先找 compose.yaml
# 2. 如果不存在,找 compose.yml
# 3. 如果不存在,找 docker-compose.yaml
# 4. 如果不存在,找 docker-compose.yml
# 5. 如果都不存在,报错
环境变量支持:
# 可以设置多个文件,用冒号分隔(Linux/Mac)
export COMPOSE_FILE=docker-compose.yml:docker-compose.override.yml
# Windows用分号分隔
set COMPOSE_FILE=docker-compose.yml;docker-compose.override.yml
📂 配置文件命名建议
推荐结构:
project/
├── docker-compose.yml # 基础配置
├── docker-compose.override.yml # 开发环境覆盖配置(默认会自动加载)
├── docker-compose.prod.yml # 生产环境配置
└── docker-compose.test.yml # 测试环境配置
多环境使用示例:
# 开发环境(默认加载 docker-compose.yml + docker-compose.override.yml)
docker compose up
# 生产环境
docker compose -f docker-compose.yml -f docker-compose.prod.yml up
# 测试环境
docker compose -f docker-compose.yml -f docker-compose.test.yml up
⚠️ 重要注意事项
1. override 文件的特殊行为
docker-compose.override.yml 会被自动加载(如果存在)
- 它会与主配置深度合并,覆盖相同的配置项
2. 版本兼容性
# Docker Compose v2+(推荐)
services:
web:
image: nginx:alpine
# Docker Compose v1(旧格式)
version: '3.8' # 需要指定版本
services:
web:
image: nginx:alpine
3. 配置文件查找示例
# 场景1:当前目录有 compose.yaml
/app/compose.yaml # ✅ 使用这个
# 场景2:当前目录有 compose.yml 和 docker-compose.yml
/app/compose.yml # ✅ 优先使用这个(忽略 docker-compose.yml)
/app/docker-compose.yml # ❌ 不会使用
# 场景3:使用 -f 参数
docker compose -f custom.yml up # ✅ 强制使用 custom.yml
🎯 最佳实践
统一使用一个命名规范(团队内保持一致)
优先使用 compose.yaml(更简洁)
多环境配置使用 -f 明确指定
使用 .env 文件管理环境变量
版本控制中排除敏感配置
# 示例:典型的项目配置
myapp/
├── .env # 环境变量
├── compose.yaml # 主配置
├── compose.override.yaml # 开发覆盖配置
├── compose.prod.yaml # 生产配置
└── .gitignore # 忽略敏感文件
这样的设计让 Docker Compose 既灵活又保持配置的清晰性。