在 Docker Compose 项目中，环境变量可能同时来自宿主机 Shell、项目目录下的 .env 文件、Compose 配置中的 environment 与 env_file，以及镜像内的 ENV 指令。配置来源一多，就容易出现“本地正常、服务器异常”“修改 .env 后没有生效”等问题。🔍 排查这类故障的关键，不是反复重启容器，而是先分清变量插值与容器环境变量，再按照优先级确认最终值来自哪里。
一、先理解两类环境变量
变量插值发生在 Compose 解析配置时。例如镜像标签、端口或 environment 中引用的 ${APP_ENV}，需要先从宿主机 Shell、默认 .env 文件或 --env-file 指定的文件中取值，然后生成实际配置。
容器环境变量则是容器启动后能够读取到的变量，通常由 environment、env_file、命令行参数或镜像 ENV 提供。需要特别注意：项目根目录中的 .env 主要用于 Compose 插值，并不会自动把其中全部变量注入容器。只有变量被 Compose 配置引用，或通过 env_file 等方式明确传入时，应用才能读取。
二、容器环境变量的优先级
当同一个变量由多个来源定义时，可以按以下顺序理解，越靠前优先级越高：
- docker compose run -e 在命令行中显式传入的值。
- environment 或 env_file 中通过宿主机 Shell、.env、--env-file 插值得到的值。
- Compose 文件 environment 中直接设置的值。
- Compose 文件 env_file 指定文件中的值。
- 镜像 Dockerfile 中通过 ENV 设置的默认值。
例如，env_file 中设置 APP_MODE=test，而 environment 中直接设置 APP_MODE=production，容器最终得到 production。镜像内的 ENV 通常只是兜底值；只要 Compose 层或运行命令提供了同名变量，镜像默认值就会被覆盖。完整规则可参考 Docker Compose 环境变量优先级官方文档。
三、Shell 与 .env 的覆盖关系
假设 Compose 文件引用 ${APP_PORT}，宿主机 Shell 中已经执行过 APP_PORT=9000，而项目 .env 文件中写的是 APP_PORT=8080，那么插值通常会采用 Shell 中的 9000。⚠️ 这也是“同一份代码在不同终端表现不同”的常见原因：开发者可能忘记自己此前导出过某个变量。
使用 --env-file 指定文件时，应把它理解为插值数据源；而服务配置中的 env_file 主要用于向容器注入变量。两者名称相似，但作用阶段不同。不要仅凭文件名判断变量一定进入了容器。
四、多份 Compose 文件如何覆盖
使用多个 -f 参数加载配置时，后面的 Compose 文件会在合并过程中覆盖或扩展前面的配置。例如先加载基础配置，再加载生产环境配置，生产文件中的同名 environment 项通常会覆盖基础值。对于端口、卷、网络等配置，合并行为可能与单值字段不同，因此不能简单理解为“后一份文件完全替换前一份”。
排查时应直接执行 docker compose -f compose.yaml -f compose.prod.yaml config。该命令会输出插值和合并后的最终模型，比逐个阅读源文件更可靠。如果只想查看环境插值来源，也可以使用 docker compose config --environment 辅助检查。
五、推荐的排查步骤 🛠️
- 检查当前 Shell：使用 env 或 printenv 查看同名变量，排除终端遗留值和 CI/CD 平台注入值。
- 确认实际工作目录：Compose 查找默认文件和 .env 时会受到当前目录、--project-directory 与 -f 参数影响。
- 生成最终配置：运行 docker compose config，重点检查 image、environment、env_file、ports 等字段是否符合预期。
- 确认容器内的真实值：对已运行服务使用 docker compose exec 服务名 env；对一次性任务可使用 docker compose run --rm 服务名 env。
- 检查启动方式：比较 docker compose up、docker compose run 与自动化脚本的参数，尤其留意 -e、--env-file、-f 和工作目录。
- 重建而非只重启：环境配置发生变化后，单纯 restart 通常不会重新创建容器，应使用 docker compose up -d --force-recreate。
六、常见误区与修复建议
误区一：修改 .env 后执行 restart
restart 主要重启现有容器，不一定重新解析并应用新的环境配置。建议先通过 config 验证结果，再执行 up -d 触发必要的重建。
误区二：认为 env_file 能覆盖 environment
同名变量同时存在时，environment 的优先级高于服务中的 env_file。建议把公共默认值放入 env_file，把少量环境差异放入覆盖文件，避免在多个位置重复定义。
误区三：只检查配置文件，不检查运行结果
配置看起来正确，不代表当前容器就是按该配置创建的。旧容器、部署脚本和命令行参数都可能造成偏差，因此必须同时核对 docker compose config 与容器内 env 的结果。
误区四：把敏感信息提交到仓库
数据库密码、访问令牌等内容不应硬编码在 Compose 文件或公开的 .env 中。🔐 可以提交 .env.example 说明变量名称与用途，真实值则通过部署平台的密钥管理、受控文件或安全注入机制提供。
实用原则：先找“最终配置”，再查“变量来源”，最后验证“容器实际值”。不要根据某一个源文件推测运行结果。
总结
Docker Compose 环境变量问题的本质，是多个配置来源在不同阶段发生插值、合并与覆盖。掌握命令行、Shell、.env、environment、env_file 和镜像 ENV 的边界后，大多数故障都能快速定位。日常维护中应减少同名变量的重复定义，固定启动目录与 Compose 参数，并把 docker compose config 和容器内 env 检查纳入部署流程。这样既能降低环境差异带来的风险，也能让配置覆盖关系更加透明、可审计。✅
