在维护多个部署环境时，经常会遇到同一个 Compose 项目需要在开发、测试、生产环境读取不同配置的情况。常见做法是把变量拆到多个 env 文件里，但一旦文件变多，哪个值最终生效就成了最容易踩坑的问题。这里记录一下我在配置多个 env 文件时的优先级判断方法和检查步骤。

env_file 多文件的覆盖顺序

在 compose.yaml 中通过 env_file 可以列出多个文件，例如：

env_file:
  - ./base.env
  - ./prod.env

当这些文件存在同名变量时，排在后边的文件会覆盖前边的文件，因此 prod.env 中的值会覆盖 base.env 中的值。这个顺序与 docker run --env-file 不同，后者只能指定一个文件。如果你希望某些值不被覆盖，可以把它们放到后面的文件中，或者使用 environment 字段显式指定。

这个规则其实很容易理解，但实际操作时会有个迷惑点：文件里变量多的时候，后一个文件会直接覆盖前一个文件里的同名项，并不管你是否在 base.env 里写了注释说“这个值不要被改”。所以我在组织文件顺序时，通常把最通用的默认配置放在第一个，把环境特有配置放在后面，后面文件里没有出现的变量仍然继承前面文件的值。

.env、--env-file 与 environment 的层级关系

Docker Compose 中多个 env 文件同时存在时，优先级从低到高依次为：默认的 .env 文件、通过 --env-file 指定的文件、以及 compose.yaml 中 environment 字段直接定义的值。注意，这里说的 .env 文件优先级最低，它主要用于变量替换，而容器内部环境变量则完全由 environment 和 env_file 控制。如果你在多个位置定义了同名变量，最终生效的是 highest priority 的值，建议先用 docker compose config 查看合并后的实际配置。

这里要区分两个作用域：一个是 Compose 文件本身的变量替换，另一个是容器内部的环境变量注入。默认的 .env 文件只参与前者，它不会自动成为容器里的环境变量。--env-file 指定的文件同样只参与变量替换，但它能改变 compose.yaml 里 ${VAR} 的取值，从而影响最终生成的容器配置。environment 字段则直接作用于容器内部，并且优先级最高，会和 env_file 注入的变量发生覆盖关系。

容易忽略的边界和坑

注意 .env 文件不参与容器内环境变量的注入，它只用于 compose.yaml 中的变量替换。如果你在 .env 里定义了一个变量，但没有在 environment 或 env_file 中引用它，容器内是读不到的。另外，env_file 中每一行必须是 KEY=VALUE 格式，不能有 export 前缀，也不能有空行分隔，否则 docker compose 会报错。文件编码建议使用 UTF-8，避免 Windows 下出现乱码。

还有一个常见混淆点：同时使用 --env-file 参数和 compose.yaml 中的 env_file 时，--env-file 指定的文件仅用于替换 compose.yaml 中的变量，而不会覆盖 env_file 注入到容器内的同名变量。换句话说，--env-file 影响的是 Compose 文件的解析结果，env_file 影响的是容器启动时的环境变量列表，这两条路径在逻辑上是分开的，不要指望命令行参数能直接覆盖配置文件里指定的容器变量。

配置建议与验证方式

配置多个 env 文件时，建议把公共变量放在一个 base.env 中，把环境特有变量放在单独的 staging.env、prod.env 文件中，然后在 compose.yaml 中按 base 在前、特定环境在后的顺序列出。这样既能减少重复，又可以明确覆盖关系。检查实际生效值时，运行 docker compose config，会输出解析后的完整配置，重点对比同名变量是否是你预期的值。

如果发现某个变量没有按预期生效，按照这个顺序排查：先看 compose.yaml 的 environment 字段里是否写了同名变量，再看 env_file 中的顺序，最后检查 .env 和 --env-file 是否参与了变量替换。要确认容器内的最终值，可以执行 docker compose exec service printenv 查看实际环境变量，变量很多时也可以先把 docker compose config 的输出保存到文件，再用 grep 搜索具体名称。

我在本地测试时，经常会故意在 base.env 和 prod.env 里放一个不同值的同名变量，然后运行 docker compose config 观察哪个值被保留。这个办法比直接启动容器更快，也能避免因为镜像启动失败而误判变量注入问题。你还可以在 env 文件中写注释标注预期来源，但要注意注释只对人工维护有帮助，Compose 解析时会正常忽略注释行，不会影响优先级。

最后提一个操作上的限制：如果 compose.yaml 中某个变量值需要从命令行临时覆盖，最直接的方式是修改 environment 字段，而不是靠增加 --env-file 参数。因为 environment 的优先级始终高于文件注入，这样做能避免猜测最终覆盖关系。具体行为可能因 Docker Compose 版本有细微差别，建议在你自己的版本上跑一次 docker compose config 确认。