Docker Compose区分 env_file 与 environment 覆盖关系的实现方法

Docker Compose 里，env_file 适合承载一组可复用的默认值，environment 适合把当前服务必须明确的值写在服务定义旁边。同一个变量同时出现时，Compose 会让 environment 的显式值优先于 env_file；如果显式值来自 shell 或 .env 插值，还要把插值来源一起算进来。

官方文档：https://docs.docker.com/compose/how-tos/environment-variables/

一、先确定配置入口和覆盖目标

先不要急着改文件。打开 Compose 项目管理器，按“项目面板 → compose.yaml → services → api → Environment”定位服务配置。假设基础配置希望使用 APP_MODE=staging，而本次部署明确要求 API 使用 APP_MODE=production。这两个值同时存在，才有必要讨论覆盖顺序。

成功状态是：左侧能看到目标 Compose 项目，中间选中了 api 服务，右侧列出环境变量来源，而不是把宿主机的全部变量误认为容器变量。

二、用 env_file 放默认值

在项目目录创建 config/base.env，然后按“api 服务 → Environment → Env files → Add file”填写相对路径。Compose 文档规定，服务里的 env_file 路径相对 Compose 文件位置解析。

# base.env：保存可复用的基础值，便于多个环境共用
APP_MODE=staging
LOG_LEVEL=info
API_PORT=8080

在 compose.yaml 中关联它：

services:
  api:
    image: example/api:1.0
    env_file:
      - ./config/base.env # 默认值集中放在文件中，路径相对 compose.yaml
    ports:
      - "8080:8080" # 示例端口映射，不参与变量覆盖

继续前核对三点：文件路径没有写成宿主机绝对路径，变量名没有重复拼写，文件中没有把密码等敏感信息直接提交到仓库。成功状态是配置面板显示 base.env 已挂载到 api 服务。

三、用 environment 写显式覆盖

回到“api 服务 → Environment → Inline variables → Add variable”，新增同名键 APP_MODE，值填 production。等价的 YAML 是：

services:
  api:
    env_file:
      - ./config/base.env
    environment:
      APP_MODE: production # 同名显式值覆盖 base.env 中的 staging
      LOG_LEVEL: ${LOG_LEVEL:-warn} # 插值值来自 shell 或 .env，缺省才使用 warn

此时 APP_MODE 的最终值是 production，LOG_LEVEL 则取插值来源或缺省值。不要把“Compose 项目目录中的 .env”和服务的 env_file 混为一谈：前者常用于给 Compose 文件插值，后者用于向容器环境提供变量。

成功状态是：同名键旁边标记为 Inline/environment，来源优先级高于 Env file；未被覆盖的 API_PORT 仍来自 base.env。

四、展开配置并核对容器结果

保存后在项目的“Compose 操作 → Resolved config”执行下面的命令。命令中的注释说明检查目的，实际输出不要当成文章中的界面截图。

# 展开 Compose 模型，确认插值和服务配置已合并
docker compose config

# 启动一次性 api 容器，核对真正进入容器的变量
docker compose run --rm api env | grep -E '^(APP_MODE|LOG_LEVEL|API_PORT)='

预期核对结果是 APP_MODE=production、LOG_LEVEL 为 shell/ .env 提供的值或 warn、API_PORT=8080。如果 config 与容器结果不一致，先检查是否在命令行使用了 docker compose run -e；该参数的优先级高于服务里的 environment 和 env_file。

常见问题

env_file 为什么没有覆盖 environment？

这是预期行为。同名变量在 Compose 文件中同时出现时，environment 的显式值优先；需要默认值时放入 env_file，需要当前服务强制指定时放入 environment。

只改了 .env，为什么容器值没变？

.env 主要参与 Compose 文件插值，不会凭空成为容器环境变量。只有它被 environment 或 env_file 引用时，才会影响容器；修改后重新执行 config 和一次性容器核对。

归档检查

最后把变量按“默认值、服务覆盖、命令行临时覆盖”三层记录在项目说明中，并保留一次 docker compose config 的展开结果。这样后续切换开发、测试和生产环境时，只需替换对应的 env 文件或显式覆盖项，不必靠猜测判断变量来源。