Docker API 网关改了 .env 仍不生效？插值、环境变量与容器重建排查

修改了 API 网关目录里的 .env，重新启动容器后却还是旧地址、旧超时或旧日志级别，不一定是文件没保存。配置要经过 Compose 解析、容器创建、应用读取三个环节；改对文件，只完成了第一步的输入。

本文针对使用 Docker Compose 管理的自建网关，解决“配置为什么没生效”，不提供任何特定网关通用的变量名。资料核对日期为 2026-10-22；以下为官方机制说明和排查方法，没有对真实生产网关执行重建或付费 API 调用。

1. 先确认你改的是哪一层

文件名同样叫 .env，用途可能不同。先找到部署入口，记录 Compose 版本、工作目录、项目名、所用 Compose 文件及顺序、环境文件参数、服务名和目标 Docker 环境。定时部署、面板按钮与手动终端可能使用不同的入口。

配置位置	主要作用	不能由此推定
Shell 环境、Compose 的 `.env` 或 `--env-file`	为 Compose 文件中的变量表达式提供插值来源	文件中的所有键都会进入容器
服务的 `environment` 或 `env_file`	声明注入容器的环境变量	应用一定识别这些变量名
挂载到容器中的配置文件	为应用提供一个可读取文件	应用会自动重读文件，或它优先于环境变量
网关管理后台、数据库设置、启动参数	由应用自身决定配置来源及优先级	修改宿主机 `.env` 就能覆盖后台设置

Docker 文档明确区分插值来源和容器环境：宿主机变量或 .env 本身不会自动成为容器变量，需要有相应配置把值传入。[1][2] 应用自己读取 .env 则是另一套机制，要看实际应用版本；不要把它与 Compose 自动加载混为一谈。

先选择一个应用文档明确支持、非敏感且容易观察的配置项进行核对，例如已确认的日志级别。不要用数据库地址或真实上游密钥做随意试错，也不要为了检查配置把完整环境变量打印到工单里。

2. 检查插值和注入是否被其他来源覆盖

先回答“Compose 最后准备了什么配置”，再看“容器当前运行什么配置”。config 子命令可以解析并合并 Compose 文件、解析变量，展示准备应用的模型；它不等于读取当前容器的实际环境。[3]

检查时必须沿用真实部署的文件、目录和参数。只在另一个目录打开终端查看默认配置，可能检查到完全不同的项目。完整 config 输出和它的 --environment 输出都可能包含秘密，应在受控环境查看；共享诊断记录时只摘取必要的非敏感项。仅做语法检查的 --quiet 不会告诉你变量值是否符合业务预期。

重点排查以下覆盖关系：

Shell 覆盖插值文件。 同名变量已经存在于启动 Compose 的 Shell 时，它可能覆盖 .env 或显式环境文件中的值。[1] CI、面板和手动终端的环境可能不同。
environment 覆盖服务的 env_file。 Compose 服务里显式声明的同名环境变量优先；即使它是空值或未定义形式，也不能指望自动退回文件值。[4]
多个文件有顺序。 多个 --env-file 的后者可以覆盖前者；服务 env_file 列表中的后者也可覆盖前者。[1][4] 这两种文件列表服务于不同环节，检查时分别列清楚。
一次性容器不代表常驻服务。 run 的临时环境覆盖可以改变那一次容器的值，不能用它的输出证明原常驻容器已经更新。[2]

例如，假设某个测试应用确实识别 APP_MODE：服务环境文件把它设为 test，而 Compose 的 environment 明确设为 production，容器应取后者。这是说明覆盖关系的假设，不是任何网关的实际配置名或已执行测试。

空字符串也不是“没有配置”的同义词。插值表达式 ${VAR:-default} 在未设置或为空时使用默认值；${VAR-default} 只在未设置时使用默认值。[1] 对于必须非空的输入，可按 Compose 文档使用必填校验，而不是让错误悄悄变成空值。表达式通过校验仍不证明地址、凭据或业务含义正确。

若值包含 $、引号或换行，还要查对应文件格式的解析规则。不要用全局删除引号或替换字符的方式修复真实密钥；先用不含秘密的占位值复现，再按准确格式调整。

3. 分清重启和重建

Docker 官方对 restart 的说明很直接：修改 Compose 配置后，执行重启不会应用这些变更；环境变量变更也不会因此更新。[5] 它重新启动已有容器，并不是重新用新配置创建容器。

up 则会根据服务配置或镜像变化停止并重建相应容器，保留挂载卷；--no-recreate 会阻止重建，--force-recreate 用于强制重建。[6] 这些是命令行为说明，不是让你立刻对生产环境执行强制更新。

操作前按这个顺序准备：

确认最终解析结果已经正确；结果仍错时，反复重建没有帮助。
保存上一版部署配置，确认持久化数据的位置和可恢复备份；安排能接受的中断窗口，等待在途请求收敛。
固定本次使用的镜像版本，避免“改环境变量”同时意外更新程序。检查挂载、网络、依赖和实际服务名。
按自己的 Compose 版本与部署流程更新受影响服务；核对是否真的重建了对应容器，而不是只重启进程或启动了另一项目的副本。
检查运行状态，再执行应用层验收。多副本场景逐个确认，避免请求时而落到旧实例、时而落到新实例。

重建保留挂载卷，不代表容器可写层中的临时数据也被保留。也不要为了让环境变量生效去删除数据卷。若涉及数据库或应用升级，应另按网关备份与恢复演练处理，不能用这次配置排错替代升级方案。

4. 容器里已是新值，应用为何仍用旧值

由有权限的维护者比较目标容器的配置元数据中所需的非敏感项，确认容器身份、创建时间与此次变更相符。不要整份导出环境变量：其中可能包含密钥、会话秘密和数据库口令。

容器的创建环境正确，仍只证明值被交给了容器。入口脚本可能转换变量，应用可能只在首次初始化时读取，后台数据库可能保存了另一个值；具体顺序必须查该应用、该版本的文档。新启动一个交互 Shell 看到的环境，也不等于主进程当前采用的全部配置。

现象	更值得先检查的位置
最终 Compose 配置已经是旧值或空值	Shell、文件路径、插值规则、覆盖文件与服务声明
最终配置是新值，目标容器仍是旧值	是否重建、是否更新错项目或服务、是否遗漏副本
容器环境正确，应用行为不变	变量名及版本、入口脚本、启动参数、后台或数据库配置、读取时机
请求结果有时新、有时旧	多副本、负载均衡目标、旧部署仍在接收流量
日志显示新地址，调用依旧失败	地址、协议、网络或鉴权本身；不能继续归因于环境变量加载

“后台页面显示新值”和“请求实际使用新值”也要分开。检查脱敏日志中的路由目标、配置版本标记或应用提供的安全状态信息，不记录完整凭据。需要重载、重启还是按应用流程修改后台设置，由产品文档决定。

如果配置已确认生效，但网关容器仍连接不到本地服务，可转到本地模型与 Docker 地址排查。如果问题变成请求参数在转发中丢失，则参考参数失效排查，不要把两类故障混在一起。

5. 用一张记录完成验收和回滚

为本次变更保留一行记录：北京时间、项目与服务、固定镜像版本、配置来源、预期非敏感值、解析结果、目标容器、应用采用的结果、未验证范围。记录密钥时只用管理系统里的名称或版本标识，不存真实值。

验收分三步：先确认解析结果，再确认目标容器已更新，最后用不含敏感信息的本地模拟路由验证应用行为。模拟路由必须事先确认不会回退到付费上游；它不能证明真实模型权限或真实供应商可用性。确有必要做真实调用时，由维护者在自己的授权预算内另行验证。

仅修改一个普通配置项时，回滚通常应恢复经审查的旧配置，并以同样流程重新创建需要更新的容器，再复验。若配置改变了数据库目标或触发了数据写入，回滚就不只是把文件改回去，必须先核对新写入与状态差异。不要为了恢复服务重新启用已泄露的凭据。

修复完成的条件不是“已经重启”，而是这三项一致：部署准备应用的值、目标实例得到的值、应用实际使用的值。以后通过面板或自动部署再次更新时，也应保留相同检查，防止手动终端中的临时设置掩盖问题。

6. 官方资料与适用边界

Docker Compose：插值与环境文件。核对插值来源、Shell 覆盖、多个环境文件及空值语义；本次读取官方文档仓库对应 Markdown。
Docker Compose：环境变量优先级。核对容器环境与插值来源的区别、临时覆盖。
Docker Compose：config。核对解析合并结果、插值环境与仅校验模式。
Compose Services：env_file 与 environment。核对覆盖关系、文件顺序及空值边界。
Docker Compose：restart。核对重启不会应用配置变更。
Docker Compose：up。核对重建、挂载卷及相关选项。

本文适用于 Docker Compose 的配置链路，不将其规则套用于 Swarm、Kubernetes 或任意托管平台。本篇没有可复制执行的生产操作脚本，也没有声称完成真实 Docker 重建测试；应用是否识别某个变量及何时读取，需要另查对应版本。