Docker Compose env_file 怎样区分共享变量和服务专属变量

Docker Compose 里最容易失控的不是变量太少，而是所有服务都把变量堆在同一个 environment 块里：改一个 web 端口，worker 也被迫跟着看；换一套本地配置，又不知道哪个文件最后覆盖了哪个值。更清晰的做法是按复用范围拆分：多个服务都要用的变量放在共享 env_file，只属于某个服务的变量放在该服务自己的文件或 environment 中。

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

本文围绕 Compose 文件中的 env_file、服务级 environment 和多个文件的覆盖顺序展开，不把镜像构建参数、Compose 项目目录下的默认 .env 文件和 secrets 混成同一个概念。

先把共享变量与服务差异分开

假设一个项目有 web 和 worker 两个服务。应用环境名、日志级别和数据库地址通常会被两者共同使用；HTTP 端口、调试开关属于 web，队列并发度属于 worker。这样的边界可以先落到三个文件：

env/
  default.env
  web.env
  worker.env
compose.yaml

default.env 只放共享值，web.env 与 worker.env 只放服务差异。文件名不是 Compose 的特殊关键字，真正决定作用范围的是它被哪个服务的 env_file 引用。

不要把密码因为“多个服务都需要”就直接塞进普通 env_file。Docker 官方文档明确建议敏感信息使用 secrets；本文的示例只使用演示用的非敏感配置，避免把配置组织方式误当成密钥保护方案。

在 compose.yaml 中声明每个服务的输入文件

下面的配置让两个服务都读取 default.env，再分别读取自己的文件。env_file 路径相对于 compose.yaml 所在目录解析，因此把配置文件统一放在 env/ 下后，路径也比较容易审查。

services:
  web:
    image: example/web:1.0
    # 先读共享变量，再读只属于 web 的变量。
    env_file:
      - ./env/default.env
      - ./env/web.env
    environment:
      # 端口是服务配置的一部分，直接在这里明确写出。
      WEB_PORT: "8080"

  worker:
    image: example/worker:1.0
    # worker 复用同一份共享文件，但不读取 web.env。
    env_file:
      - ./env/default.env
      - ./env/worker.env

对应文件可以保持短小：

# env/default.env：多个服务都会读取的公共变量。
APP_ENV=local
LOG_LEVEL=info
DB_HOST=db
DB_PORT=5432

# env/web.env：只给 web 服务使用的变量。
WEB_DEBUG=true

# env/worker.env：只给 worker 服务使用的变量。
WORKER_CONCURRENCY=4

这里的 WEB_PORT 放在服务级 environment，而不是放进共享文件，是为了让读者一眼看出它只属于 web。若 web 和 worker 的端口或调试模式确实相同，再把它移动到共享文件，而不是为了省一个文件盲目复用。

同名变量出现时，environment 是明确覆盖点

拆分文件之后，最需要记住的一条规则是：Compose 文件中的 environment 高于同一服务的 env_file。例如 default.env 里给出测试环境，web 服务又必须在当前编排文件中固定为生产模式：

services:
  web:
    image: example/web:1.0
    # 文件提供默认值，便于不同环境复用。
    env_file:
      - ./env/default.env
      - ./env/web.env
    environment:
      # 同名键在 Compose 文件中显式指定，覆盖 env_file 的值。
      APP_ENV: production
      WEB_PORT: "8080"

判断这类配置时，不要只问“变量写在哪个文件”，还要问“它是否在服务级 environment 再次出现”。如果只是希望所有环境都能改默认值，用 env_file；如果某个服务的最终值必须随编排文件一起固定，用 environment，并把这个覆盖意图写成注释。

多个 env_file 按顺序合并，后者覆盖前者

同一个服务可以列出多个 env_file。Compose 会按列表顺序处理它们，后面的文件可以覆盖前面已经出现的同名变量。适合把稳定公共值与本机差异分开：

services:
  web:
    image: example/web:1.0
    # local.env 放在后面，表示它可以覆盖 default.env 的同名键。
    env_file:
      - ./env/default.env
      - ./env/local.env
    environment:
      # 该值仍高于上面两个 env_file 的同名值。
      WEB_PORT: "8080"

# env/default.env：团队共享的基线。
APP_ENV=production
API_URL=https://api.example.com
TIMEOUT=30

# env/local.env：本机调试覆盖，只覆盖必要的键。
APP_ENV=development
API_URL=https://api.local
TIMEOUT=60

上例中，APP_ENV、API_URL 和 TIMEOUT 先从 default.env 进入，再由 local.env 覆盖；如果 WEB_PORT 同时在文件里出现，最后的服务级 environment 仍优先。多文件覆盖应当尽量让“后面的文件只写差异”，否则读者很难判断一个键究竟从哪里来。

用 config 展开配置，而不是凭文件顺序猜

配置文件准备好后，先查看 Compose 解析后的服务定义。下面两个命令作用不同：第一个关注 Compose CLI 用来插值的环境，第二个关注合并后的 Compose 配置。

# 查看 Compose CLI 当前用于变量插值的环境来源。
docker compose config --environment

# 输出合并后的服务配置，重点检查 env_file 路径和 environment 覆盖。
docker compose config

config 展开结果适合检查 YAML 层级、文件路径和最终服务配置，但它不是容器内环境的唯一观察点。尤其是使用了命令行 docker compose run -e 时，命令行值还会进入更高优先级层。

如果目标是确认某个临时任务真正看到的值，可以用一次性容器输出变量：

# 只打印非敏感变量，避免把密码写入终端历史或日志。
docker compose run --rm web sh -lc 'printf "APP_ENV=%s\nWEB_PORT=%s\n" "$APP_ENV" "$WEB_PORT"'

这个检查关注“容器环境最终拿到什么”，而不是只关注文件内容。若服务本身没有 sh，就改用镜像自带的命令；不要为了排查变量而临时替换生产镜像。

四个容易混淆的边界

特别是 --env-file 与服务级 env_file 不要混为一谈：前者会影响 Compose CLI 的环境与插值语境，后者用于把变量放入指定服务的容器环境。写排障记录时，把命令行参数、Compose 文件和容器内结果分成三栏，通常比继续追加变量更快定位问题。

一份可直接采用的拆分清单

1. 先列出 web 和 worker 都需要的键，只把这些键放进 default.env。
2. 按服务建立 web.env、worker.env，只保存各自差异。
3. 在每个服务的 env_file 中先列共享文件，再列服务文件。
4. 必须由编排文件固定的值放进 environment，并写清覆盖意图。
5. 运行 docker compose config 查看解析后的配置，再用一次性容器核对非敏感最终值。
6. 密码、令牌和证书不要当作普通 env_file 的示例数据，改用 Docker Compose secrets 设计。

这样拆分后，新增服务只需决定它要复用哪份共享文件，再添加自己的差异文件；修改本机环境时只动覆盖层，不会悄悄改变所有服务的共同基线。

相关问题

env_file 的路径是相对哪里？相对 Compose 文件所在位置解析，建议把配置目录固定在项目内并避免依赖调用命令时的当前目录。

environment 和 env_file 同时设置同名变量怎么办？服务级 environment 的显式值优先；若使用插值或命令行参数，还要把 CLI 与宿主机来源纳入优先级判断。

多个 env_file 能不能随意调换顺序？不能。后列文件可以覆盖前列文件，调换顺序可能改变最终值。

为什么 config 展开了变量，容器里还是不同？检查是否使用了 docker compose run -e、服务启动命令自身修改变量，或把 CLI 的 --env-file 误当成服务 env_file。