在 Docker 项目中，“明明修改了环境变量，程序却仍然使用旧值”是非常常见的问题。根因往往不是 Docker 没有读取配置，而是同名变量来自多个位置，最终值被更高优先级的配置覆盖。本文将梳理 Docker 与 Docker Compose 的环境变量覆盖规则，并提供一套可直接执行的排查流程。🔍
一、先区分两个容易混淆的阶段
排查之前，首先要区分构建阶段与容器运行阶段。Dockerfile 中的 ARG 主要用于镜像构建，例如选择软件版本；ENV 则会写入镜像配置，并成为容器运行时的默认环境变量。运行容器时通过命令行或 Compose 传入的变量，可以继续覆盖镜像中的 ENV。
还需要特别注意：项目根目录中的 .env 文件通常用于 Compose 文件的变量插值，它并不等于自动把全部变量注入容器。只有当 compose.yaml 通过 environment、env_file 或相关插值表达式引用这些值时，它们才可能进入容器环境。
二、Docker Compose 环境变量优先级
根据 Docker 官方优先级说明，同名环境变量发生冲突时，可以按以下顺序理解，位置越靠前，优先级通常越高：
- 通过 docker compose run -e 在命令行中指定的运行时变量。
- Compose 的 environment 或 env_file 中，通过宿主机 Shell、默认 .env 或 --env-file 插值得到的值。
- compose.yaml 中 environment 明确设置的固定值。
- compose.yaml 中 env_file 指定文件提供的值。
- 镜像内由 Dockerfile ENV 保存的默认值。
例如，镜像中设置 APP_MODE=production，env_file 中设置 APP_MODE=test，而 compose.yaml 的 environment 又设置 APP_MODE=staging，那么容器最终通常得到 staging。若执行一次性命令时再传入 APP_MODE=debug，则该次运行会使用 debug。✅
宿主机 Shell 和 .env 文件中的变量，不一定会直接出现在容器内。它们可能只是 Compose 解析配置时使用的“输入值”，是否注入容器取决于 compose.yaml 的具体写法。
三、为什么修改配置后没有生效
1. 只重启了旧容器
docker restart 只会停止并重新启动现有容器，不会按照新的 Compose 配置重新创建容器。环境变量属于容器创建时确定的配置，因此修改 compose.yaml、env_file 或启动参数后，应重新创建容器，而不是仅执行重启。
可先执行 docker compose up -d --force-recreate。如果同时修改了 Dockerfile、构建参数或复制进镜像的配置文件，则应执行 docker compose up -d --build --force-recreate。
2. .env 文件路径理解错误
Compose 查找 .env 文件时会受到当前工作目录、项目目录、-f、--project-directory 和 --env-file 等参数影响。从其他目录运行命令，可能导致加载的并不是预期文件。建议进入项目目录执行命令，或者明确指定配置文件与环境文件路径。
3. environment 覆盖了 env_file
如果同一个变量既出现在 env_file 中，又在 environment 中定义，那么 environment 的值优先。即使 environment 引用的是空的宿主机变量，也可能覆盖 env_file 中原本正确的值。因此排查时不能只检查 env_file，还要搜索整个 compose.yaml 中是否存在同名键。
4. 容器入口脚本再次改写变量
有些镜像会在 entrypoint.sh、启动脚本、进程管理器配置或应用启动命令中重新导出变量。此时 Docker 注入的值可能是正确的，但在应用启动前又被脚本覆盖。Node.js、Java、Shell 等应用还可能从独立配置文件读取值，使人误以为环境变量未生效。
5. 应用读取的变量名并不一致
变量名大小写敏感。DATABASE_URL、Database_URL 与 database_url 是不同变量。还要检查应用是否读取了带前缀的名称，例如框架要求 APP_DATABASE_URL，但 Compose 中只配置了 DATABASE_URL。⚠️
四、推荐的逐层排查步骤
- 查看 Compose 最终配置：执行 docker compose config，确认变量插值后的结果、env_file 路径、服务名称和 environment 内容是否符合预期。
- 检查宿主机变量：使用 printenv 或 env 查看当前 Shell 是否存在同名变量，尤其关注 CI/CD 平台、部署脚本和终端配置自动注入的值。
- 检查容器创建配置：使用 docker inspect 容器，并查看 Config.Env，确认 Docker 在创建容器时实际写入了哪些变量。
- 检查容器内进程环境：执行 docker compose exec 服务名 env，或使用 printenv 变量名查看容器当前环境。敏感值不要直接复制到日志或论坛。
- 检查启动链路：核对 Dockerfile 的 ENTRYPOINT、CMD、Compose 的 command，以及项目启动脚本，搜索 export、默认值表达式和配置文件加载逻辑。
- 重新创建容器：配置确认无误后，使用 --force-recreate 重建容器；涉及镜像内容时同时加入 --build。
- 验证应用实际读取结果：通过健康检查、状态接口或脱敏日志确认应用使用的值，不要只根据容器中存在变量就判断问题已经解决。
五、容易被忽略的特殊情况
- docker compose run 与 up 不完全相同：run 常用于一次性任务，并可通过 -e 临时覆盖变量，不能直接代表长期运行服务的配置。
- 旧镜像标签未更新：使用固定标签但未重新拉取镜像时，本地可能仍使用旧镜像，可结合 docker compose pull 后重新创建。
- 多份 Compose 文件合并：使用多个 -f 参数时，后续文件可能覆盖前面的 environment、command 或其他配置，应以 docker compose config 的合并结果为准。
- 变量值包含特殊字符：美元符号、井号、空格、引号和换行可能触发插值或解析问题。应核对 Compose 解析结果，并避免在日志中输出密码、令牌等敏感信息。
- 应用存在配置优先级：部分框架会让命令行参数、外部配置中心或挂载的配置文件覆盖环境变量，需要继续检查应用自身的配置加载顺序。
六、配置管理的实用建议
建议把 Dockerfile ENV 作为安全的默认值，把 env_file 用于不同环境的普通配置，把 environment 留给服务级明确覆盖，把命令行 -e 仅用于临时调试。生产环境中的密码、访问令牌和证书不应写入镜像、公开仓库或普通日志，可根据部署平台选择 Secrets 或专用密钥管理方案。🔐
同时，尽量减少同一个变量在多个位置重复定义。为开发、测试和生产环境建立清晰的文件命名规则，并在部署流程中固定工作目录、Compose 文件和 env 文件参数。这样不仅能降低覆盖冲突，也能让故障复现与审计更加容易。
总结
Docker 环境变量不生效，通常可以归结为三类原因：被更高优先级配置覆盖、容器没有重新创建、应用启动后再次改写或忽略变量。最有效的排查方法是沿着“宿主机输入、Compose 解析结果、容器创建配置、容器内环境、应用实际读取值”逐层核对。只要以 docker compose config 和 docker inspect 的真实结果为依据，而不是凭文件内容猜测，绝大多数环境变量问题都能快速定位。🚀
