docker compose up 命令默认配置文件自动查找规则详解

2026-04-02 11:35:01发布 2次浏览

详情描述

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

📂 配置文件命名建议

多环境使用示例：

# 开发环境（默认加载 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 既灵活又保持配置的清晰性。