Docker Compose 环境变量覆盖的文件顺序

Docker Compose 的环境变量“没有生效”，通常不是文件没被读取，而是同名变量同时来自多个层级。最容易混淆的是：Shell、项目目录的 .env 和 --env-file 主要参与 Compose 文件插值；environment、env_file 和镜像里的 ENV 才决定变量是否进入容器。

官方地址：https://docs.docker.com/compose/

排查时先把“插值”与“容器注入”分开，再按运行时优先级比较。同名变量的常见优先顺序是：docker compose run -e 最高，其次是带插值结果的 environment 或 env_file，再是 Compose 文件中直接写出的 environment，然后是 env_file，最后才是镜像 ENV。

先分清变量替换和容器注入

.env 里的变量不会因为文件存在就自动出现在容器中。比如 Compose 文件写成 image: "app:${APP_TAG}" 时，APP_TAG 用来替换镜像标签；只有服务下的 environment 或 env_file 明确引用它，变量才会进入容器环境。

services:
  web:
    # APP_MODE 用于 Compose 插值，同时显式注入容器
    image: "example/web:${APP_TAG:-latest}"
    environment:
      # ${APP_MODE:-development} 在 shell 或 .env 中取值
      APP_MODE: ${APP_MODE:-development}
    env_file:
      # 这个文件提供服务级默认变量
      - ./web.env

如果只写 image 而没有 environment 或 env_file，宿主机的 APP_MODE 不会凭空复制到容器。列表写法 - APP_MODE 是另一种含义：它要求 Compose 从运行 Compose 的 Shell 中传递同名变量。

同名变量按什么顺序覆盖

针对容器最终环境，可以先记住一条速查顺序：docker compose run -e → 带插值的 environment 或 env_file → Compose 文件中的 environment → 服务的 env_file → 镜像 ENV。这里的“带插值”很关键，因为 environment: APP_MODE: ${APP_MODE} 的值可能来自 Shell 或 .env，而不是把它们当成另一条独立的容器注入层。

services:
  web:
    image: example/web:1.0
    # 直接写在 environment 中，会覆盖同名 env_file 值
    environment:
      APP_MODE: production
      # 省略等号表示从当前 Shell 传入，未设置时不会自动填充
      DEBUG
    env_file:
      - ./web.env

假设 web.env 有 APP_MODE=staging，镜像有 ENV APP_MODE=development，那么容器里的 APP_MODE 是 production。如果再用 docker compose run -e APP_MODE=test web 启动一次性容器，命令行值会继续覆盖前面的配置。

用最小配置复现“覆盖了但看不懂”

排错时不要一次改动多个文件。可以为同一个变量准备三份不同值，再只改变一层，观察最终值来自哪里。

# .env：只用于 Compose 文件插值的默认值
APP_MODE=from-dotenv

# web.env：服务 env_file 的值
APP_MODE=from-env-file

# compose.yaml：environment 的明确值优先于 env_file
services:
  web:
    image: example/web:1.0
    environment:
      # 用固定值先确认覆盖链路是否按预期工作
      APP_MODE: from-environment
    env_file:
      - ./web.env

如果文章中的变量只是用于替换镜像标签或端口，不要用“容器内打印变量”的方式判断插值是否成功；反过来，如果问题是应用读取不到变量，就要检查服务下是否存在 environment 或 env_file。两种现象看起来相似，检查入口不同。

用 docker compose config 找到最终值

docker compose config 会把 Compose 文件解析成规范化模型并展开变量。它适合回答“Compose 现在理解的配置是什么”，而不是替代应用启动后的运行时检查。

# 查看用于插值的环境来源，便于确认 .env 和 Shell 的输入
docker compose config --environment

# 展开 Compose 模型，查看 web 服务最终的 environment 与 env_file
docker compose config

# 只保留规范化 YAML，方便与另一份配置做文本对照
docker compose config --format yaml

如果 config --environment 中没有预期变量，先检查当前工作目录、--env-file 参数以及 Shell 是否真的导出了该变量；如果环境来源正确但服务模型中没有它，再回到 environment 或 env_file 检查是否显式注入。使用多个 -f 文件时，还要注意后加载的配置会参与合并，不能只看基础文件。

速查表和常见误区

不要把密码、访问令牌等敏感信息直接提交到 .env 或 Compose 文件中。需要更严格的保管边界时，应结合 Docker 的 secrets 机制；本文的优先级规则主要用于定位普通配置变量，不代表敏感信息适合通过环境变量长期保存。

相关问题

为什么修改 .env 后容器里的值没变？因为 .env 只参与插值，或服务已经被更高优先级的 environment、env_file 或 run -e 覆盖；先用 docker compose config 查看当前模型。

environment 和 env_file 能一起写吗？可以。两者存在同名变量时，服务的 environment 值优先。

如何确认 --env-file 真的被使用？显式运行 docker compose --env-file ./staging.env config --environment，再检查服务配置中是否引用了相应变量。