Docker Compose环境变量不生效，先不要反复修改.env。Compose至少涉及两个阶段：启动前把${VAR}替换进配置文件，以及容器创建时把环境变量写入容器。env_file主要服务于第二阶段，不会自动成为所有Compose字段的插值来源。
最可靠的排错顺序是：先用docker compose config查看最终配置，再检查容器内环境，最后确认旧容器是否已经重建。只看磁盘上的.env或compose.yaml，无法证明运行中的容器采用了哪个值。
先把三个容易混淆的文件角色分开
| 位置 | 主要作用 | 常见误解 |
|---|---|---|
Shell、.env或--env-file |
为Compose配置中的${VAR}提供插值值 |
以为服务的env_file也会自动参与所有插值 |
services.*.environment |
直接定义容器环境变量 | 忘记它通常会覆盖env_file中的同名值 |
services.*.env_file |
把文件中的键值传给容器 | 以为修改文件后重启旧容器就会更新环境 |
例如，镜像标签、端口映射和卷路径里的${VAR}在容器创建前就已经解析；而应用在容器中读取的APP_MODE，取决于environment、env_file、命令行覆盖和镜像默认值。
一个典型误区：env_file里有值，镜像标签仍然为空
services:
app:
image: example/app:${APP_TAG}
env_file: [app.env]
environment:
LOG_LEVEL: ${LOG_LEVEL:-info}APP_TAG=v2
LOG_LEVEL=debug如果第二段保存为服务的app.env，它会把变量传进容器，但不应假定它会给image: example/app:${APP_TAG}提供插值。要让APP_TAG参与Compose文件插值，可把值放入当前项目使用的.env、导出到Shell，或运行时明确指定--env-file。
docker compose --env-file app.env config
docker compose --env-file app.env up -d项目目录、-f指定的Compose文件位置和命令执行目录会影响默认文件查找。排错时不要凭文件名猜加载结果，应让Compose输出它实际解析后的配置。
用config看到容器创建前的最终配置
docker compose config
docker compose config --environmentdocker compose config会渲染合并后的Compose模型，适合检查镜像标签、端口、卷路径和environment值。支持--environment的版本还可显示用于插值的环境来源结果。输出中如果已经是错误值，问题在容器创建之前；输出正确而应用仍读到旧值，再转向容器生命周期和应用自身配置。
配置输出可能包含敏感变量。生产环境检查时只截取必要字段，工单和聊天记录中应替换令牌、密码与私有地址。
容器内同名变量按哪一层覆盖
诊断时可以先使用一个无敏感信息的测试变量。常见覆盖关系是：运行命令显式传入的-e优先级最高；服务的environment会覆盖env_file中的同名键；env_file又会覆盖镜像Dockerfile中的ENV默认值。Shell和.env还可能先参与environment字段的插值，因此要以渲染结果为准。
docker compose run --rm -e APP_MODE=diagnostic app env
docker compose exec app env第一条会创建一次性容器并显式覆盖变量，适合验证应用能否读取该键；第二条读取正在运行的容器环境。不要在真实生产容器中直接输出全部环境，否则数据库密码、访问令牌和私有端点可能被一并打印。
改了文件只restart，旧环境为什么还在
容器环境在创建时写入。docker compose restart只是停止并重新启动现有容器，不会因为.env或env_file变化就重新创建容器。确认渲染配置正确后，应安排可回滚的重建：
docker compose up -d --force-recreate app
docker compose exec app printenv APP_MODE重建前先确认数据已放在卷或外部存储中，并评估短暂中断。环境值正确但应用仍不变，还要检查应用配置文件、启动参数、缓存、密钥挂载和进程是否在启动时把值复制到其他位置。
逐层定位而不是同时改五个文件
- 确认项目：记录当前目录、Compose文件和项目名，避免操作到另一套容器。
- 检查插值：运行
docker compose config，确认${VAR}已经变成预期值。 - 检查覆盖：搜索
environment、env_file、命令行-e和镜像ENV的同名键。 - 检查容器：只读取目标变量，确认运行中的容器是否仍保留旧值。
- 安全重建：确认数据卷与回滚方案后重新创建服务。
- 检查应用：区分容器环境正确和应用业务配置正确，不要把两者合并判断。
如果问题同时涉及构建阶段、容器运行阶段和Docker守护进程代理，可阅读Docker Compose三层代理配置边界，避免把构建参数写进运行环境。
在VPS上部署时保留重建和回滚条件
用于容器测试的VPS应具备控制台入口、快照或可靠备份，并在变更前记录当前镜像摘要、Compose配置和卷位置。极跃圈收录的雨云云服务详情页记录的邀请码为admin01；实际产品配置、快照能力、优惠和使用限制以当前结算页面与服务条款为准。
不要把生产密钥永久写进公开仓库或镜像层。需要敏感配置时，应结合访问权限、Secrets或专用密钥管理方式设计，而不是依赖文件名看起来隐蔽。
