Docker Compose 怎样使用 env_file 管理服务变量

Docker Compose 使用 env_file 管理服务变量时，核心做法是在服务节点下声明变量文件，让 Compose 把文件中的键值注入容器环境。这样可以把经常变化的端口、运行模式和连接地址从 compose.yaml 的结构配置中拆出来；需要覆盖时再按顺序追加文件。

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

下面用一个名为 api 的服务演示完整路径：准备文件 → 绑定 env_file → 查看合并结果 → 处理覆盖和敏感信息。

一、先准备默认变量文件

建议把稳定的非敏感默认值放在项目目录下的 env/app.env，例如服务端口、运行模式和日志级别：

APP_PORT=8080
APP_MODE=dev
LOG_LEVEL=info

变量文件使用简单的 KEY=VALUE 形式即可。密码、访问令牌等敏感信息不要直接提交到仓库；Docker 官方建议这类数据使用 secrets，而不是普通环境变量。

二、在服务配置中填入 env_file

打开项目根目录的 compose.yaml，进入 services.api，添加 env_file。路径按 compose.yaml 所在位置解析：

services:
  api:
    image: example/api:stable
    # env_file 的相对路径以 compose.yaml 所在目录为基准
    env_file:
      - ./env/app.env
    ports:
      - "8080:8080"

这里的关键不是把文件写在顶层，而是把它放在具体服务下。多个服务可以分别引用不同的变量文件，也可以引用同一个文件，从而避免在每个服务的 environment 区块中重复维护相同变量。

三、启动前查看 Compose 合并后的配置

配置完成后，先在包含 compose.yaml 的目录执行 docker compose config。它适合查看 Compose 解析后的结构，重点是确认目标服务已经挂载了正确的变量文件：

# 只展开 Compose 配置，不启动容器
docker compose config

如果只是想确认容器启动后的环境，可以启动服务后读取目标容器的环境变量：

# 以服务名读取容器中的变量，便于定位拼写或路径问题
docker compose run --rm api env | grep -E '^(APP_PORT|APP_MODE|LOG_LEVEL)='

输出为空时，优先检查三点：env_file 是否缩进到目标服务下、文件路径是否相对 compose.yaml、变量名是否与程序读取的名称完全一致。

四、需要覆盖时按顺序追加文件

开发环境可以保留一份默认文件，再追加一份本地覆盖文件。多个文件会按列出的顺序处理，后面的值可以覆盖前面的值：

services:
  api:
    image: example/api:stable
    # 后面的 local.env 会覆盖同名变量
    env_file:
      - ./env/app.env
      - ./env/local.env

local.env 可以只写需要改变的键：

# 只覆盖本地开发所需的值
APP_MODE=local
LOG_LEVEL=debug

如果某个覆盖文件不是每台机器都具备，可以使用对象写法把它设为可选：

services:
  api:
    # default.env 必须存在；local.env 缺失时静默跳过
    env_file:
      - path: ./env/app.env
        required: true
      - path: ./env/local.env
        required: false

需要一次性试运行时，可以用 docker compose run -e 临时覆盖变量，不必修改文件：

# 只对这次临时任务覆盖模式，不改动 env 文件
docker compose run --rm -e APP_MODE=test api env | grep '^APP_MODE='

五、常见误区与选择建议

还要注意，env_file 负责把变量设置到容器环境；它与 Compose 用于插值的项目级 .env 文件不是同一个概念。遇到“配置文件里能展开、容器里却没有变量”的情况，应分别检查插值来源和服务环境来源。

六、快速记忆

1. 把默认变量写到独立的 KEY=VALUE 文件。
2. 在目标服务下配置 env_file，路径相对 compose.yaml。
3. 用 docker compose config 和临时容器命令查看结果。
4. 多文件按顺序覆盖，缺失的本地文件可用 required: false。
5. 密码和令牌不要放进普通 env_file。

相关问题

env_file 的路径是相对哪里计算的？

相对 compose.yaml 所在目录计算，不是相对当前 shell 的任意目录。

多个 env_file 谁的值优先？

按列表顺序处理，后面的文件可以覆盖前面文件中的同名变量。

env_file 能不能替代 secrets？

不能把它们视为同一机制。普通变量文件适合非敏感配置；密码、令牌等敏感信息应使用专门的 secrets 方案。