在 Docker 项目中，环境变量常被用于配置数据库地址、运行模式、端口和第三方服务凭据。问题在于，同一个变量可能同时出现在 Dockerfile、Compose 文件、.env 文件、宿主机 Shell 和启动命令中。最终生效的值与预期不一致时，应用就可能出现连接失败、配置未更新或环境混用等问题。本文将梳理覆盖优先级，并给出一套可直接执行的排查流程。🔍
一、先区分“变量插值”和“容器环境变量”
排查前必须理解两个容易混淆的概念。Compose 的“变量插值”发生在解析 compose.yaml 时，例如镜像标签、端口或 environment 字段中的 ${APP_ENV}；“容器环境变量”则是容器创建后，通过进程环境传递给应用的值。
.env 文件通常用于给 Compose 提供插值来源，并不代表其中的每个变量都会自动进入容器。只有当变量被 environment、env_file 等配置引用，或者通过命令行显式传入时，它才可能成为容器内可见的环境变量。⚠️
二、Docker Compose 环境变量覆盖优先级
当同名变量来自多个位置时，可以按照从高到低的顺序理解：
- docker compose run -e 等命令行参数显式指定的值。
- environment 或 env_file 中通过宿主机 Shell、.env 或 --env-file 插值得到的值。
- Compose 文件 environment 字段直接设置的固定值。
- Compose 文件 env_file 字段加载的值。
- 镜像 Dockerfile 中 ENV 指令设置的默认值。
例如，镜像中设置 APP_ENV=production，env_file 中设置 APP_ENV=test，而 compose.yaml 的 environment 又写了 APP_ENV=staging，那么容器通常会得到 staging。若启动时执行 docker compose run -e APP_ENV=debug，则 debug 的优先级更高。完整规则可参考 Docker 官方环境变量优先级文档。
需要特别注意：宿主机 Shell 和 .env 主要提供插值来源。它们不会在没有 Compose 配置引用的情况下，自动把所有变量注入容器。
三、Dockerfile 中 ARG 与 ENV 的区别
ARG 主要用于镜像构建阶段，可通过 docker build --build-arg 传入。除非后续使用 ENV 将其写入镜像环境，否则 ARG 通常不会直接出现在运行中的容器里。
ENV 会保存到镜像配置中，并作为容器运行时的默认环境变量。不过，这个默认值可以被 docker run -e、Compose 的 environment 或 env_file 覆盖。因此，修改 Dockerfile 中的 ENV 后，如果没有重新构建镜像，已有镜像和容器不会自动获得新值。🧱
四、为什么修改配置后没有生效
1. 只重启容器，没有重新创建
docker restart 只是停止并重新启动原容器，不会根据最新 Compose 配置重新创建容器。修改 environment、env_file 或镜像后，应执行 docker compose up -d --force-recreate。若 Dockerfile 也发生变化，可执行 docker compose up -d --build --force-recreate。
2. .env 文件位置或用途理解错误
Compose 查找 .env 时会受到当前工作目录、项目目录、-f 和 --project-directory 等参数影响。建议在项目根目录执行命令，并使用 docker compose config 检查插值后的最终配置。若使用自定义文件，应明确指定 docker compose --env-file ./config/prod.env config。
3. environment 覆盖了 env_file
Compose 文件中同时存在 environment 和 env_file 时，同名变量通常由 environment 覆盖。即使 environment 中的值为空，也可能覆盖 env_file 中原本有效的配置，因此不要把无值变量当作普通占位符使用。
4. 应用没有真正读取环境变量
有些应用会优先读取自身配置文件、启动脚本参数或框架配置中心。启动命令也可能在进程前临时设置变量，从而覆盖容器传入的值。此时 Docker 环境变量本身可能正确，但应用使用的是另一个配置来源。
5. 查看了镜像配置，而不是容器实际环境
docker image inspect 反映的是镜像默认配置，不能完整代表运行中容器的最终状态。排查时应检查具体容器，并进入容器查看目标进程能够读取到的变量。
五、推荐的逐层排查步骤
- 检查 Compose 最终配置：
执行 docker compose config，确认变量是否已经按预期完成插值。 - 确认目标容器身份：
执行 docker compose ps，避免检查旧容器、同名容器或其他项目创建的实例。 - 查看容器配置：
执行 docker inspect 容器名，在 Config.Env 中查找目标变量。 - 检查容器内部环境：
执行 docker compose exec 服务名 env，并结合 grep 筛选目标变量。 - 检查应用进程：
确认启动脚本、入口脚本、配置文件和命令行参数是否再次覆盖变量。 - 重新创建并复查：
使用 --force-recreate 重建容器，再重复执行 config、inspect 和 exec 检查。
如果变量包含空格、美元符号、井号或换行内容，还要检查引号和转义规则。敏感信息不应直接打印到共享日志中，建议只验证变量是否存在，或对输出进行脱敏处理。🔐
六、降低环境变量冲突的实践建议
- 让 Dockerfile ENV 只保存安全、通用的默认值，不写真实密码和令牌。
- 在 Compose 中明确区分本地、测试与生产环境的 env_file。
- 避免同一变量在多个层级重复定义，减少隐式覆盖。
- 部署前执行 docker compose config，把最终配置检查加入发布流程。
- 修改运行时配置后重新创建容器，不要仅依赖 restart。
- 为关键变量设置启动校验，缺失时让应用输出清晰错误并停止启动。
总结
Docker 环境变量不生效，通常不是变量“消失”，而是被更高优先级配置覆盖、停留在插值阶段、没有重新创建容器，或者被应用自身配置再次改写。排查时应遵循“Compose 最终配置、容器配置、容器内部环境、应用进程实际读取值”的顺序逐层确认。掌握覆盖优先级，并减少同名变量的重复定义，就能让配置来源更透明，也能显著缩短故障定位时间。✅
