Docker Compose v2 多环境配置 env 文件怎么管理

Docker Compose v2 管理多环境 env 文件推荐使用`--env-file`参数配合多个 compose 文件叠加，适用于开发、测试、生产环境隔离场景，风险边界在于后加载的文件会覆盖先加载的同名变量。

先说结论：Docker Compose v2 通过文件叠加和变量优先级机制实现多环境配置，核心是分离通用配置与环境特有配置。

适合：需要在开发、测试、生产环境间切换配置且避免硬编码的场景
先准备：创建基础docker-compose.yml及不同环境的.env或覆盖文件
验收：使用docker compose config确认最终渲染配置无误后再启动

命令速用版

直接通过命令行指定环境文件启动服务，后指定的文件变量会覆盖先前的定义。

# 加载基础配置和生产环境配置
docker compose `--env-file` .env.common `--env-file` .env.production up -d

# 组合多个 compose 文件
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

为什么会这样

Docker Compose 环境变量加载遵循特定的优先级顺序，确保配置灵活性的同时允许局部覆盖。

变量加载优先级从高到低依次为：服务中environment显式定义的变量优先级最高，其次是`--env-file`指定的文件内容，最后是项目根目录默认读取的.env文件。这种机制允许开发者将敏感信息或环境差异参数外置，无需修改核心编排文件即可适配不同运行环境。

分步处理

按以下步骤构建可维护的多环境配置体系，确保配置隔离且易于验证。

步骤 1：规划文件结构
在项目根目录建立基础配置文件与环境专属文件，建议将敏感配置纳入.gitignore。

project/
├── docker-compose.yml
├── .env.example
├── .env.common
├── .env.development
└── .env.production

步骤 2：定义变量内容
在.env.common中定义通用变量，在环境专属文件中定义差异变量，注意键值对之间不能有空格。

# .env.common
LOG_LEVEL=info
DB_HOST=localhost

# .env.production
DB_HOST=prod-db.internal
LOG_LEVEL=error

步骤 3：在 Compose 文件中引用
使用env_file指令或直接在environment中引用变量，支持使用${VAR:-default}语法设置默认值。

services:
  app:
    image: myapp:v1
    env_file:
      - .env.common
    environment:
      - ENV_MODE=${ENV_MODE:-production}

步骤 4：启动与覆盖
运行启动命令时按顺序加载文件，确保生产环境文件在后以覆盖开发配置。

怎么验证是否生效

在启动容器前和启动后分别进行配置检查，确保变量已正确注入。

检查渲染配置：使用config命令查看合并后的最终配置，确认环境变量值符合预期。

docker compose `--env-file` .env.production config

检查容器环境：进入运行中的容器查看实际环境变量，确认无缺失或错误。

docker exec -it <container_id> env | grep DB_HOST

常见坑

空格问题：env 文件中键值对等号周围不能有空格，如KEY = value是非法格式，会导致解析失败。
自动加载冲突：Compose 默认自动加载根目录.env，若同时使用`--env-file`需注意变量覆盖顺序。
敏感信息泄露：务必将包含密码密钥的.env文件加入.gitignore，仅提交.env.example模板。
优先级误解：服务内environment字段优先级高于env_file，若需文件覆盖需在文件中定义而非 compose 内硬编码。

常见问题

多个 env 文件加载顺序是怎样的？

后加载的文件会覆盖先加载文件中的同名变量，通常先通用后特定。

如何在 compose 文件中设置变量默认值？

使用${VAR_NAME:-default_value}语法，当变量未定义时自动使用默认值。

system 环境变量和.env 文件哪个优先级高？

在 Compose 文件插值解析时，宿主系统环境变量优先级通常高于.env文件，但容器内运行环境以 compose 配置为准。

参考来源

【微服务部署必看】:Docker Compose 多 env 文件配置的 7 大最佳实践-CSDN 博客
Docker Compose 环境变量配置详解 - 直角漫步 - 博客园
Docker Compose 多 env 文件实战：快速搭建开发、测试、生产三套环境
揭秘 Docker Compose `--env-file`:如何高效管理多环境变量配置
Docker Compose 多环境配置管理：使用环境变量与配置文件