Docker Compose 怎样为单服务注入 env 文件

在 Docker Compose 中，只给某一个服务注入 env 文件，应把 env_file 写在该服务的配置节点下，例如 services.api.env_file。其他服务不会因为文件放在项目目录里就自动获得这些变量。修改后要让该服务的容器按新配置重建，单纯重新打开文件或重启应用进程并不等于更新容器环境。

官方地址：https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/

开始前：确定服务名与配置入口

本文使用当前 Docker Compose CLI 的 docker compose 命令形式。需要已安装 Docker 和 Compose、引擎可用，并能访问示例镜像。操作对象是一个演示项目，包含 api 与 worker 两个服务；实际项目应保留自己的镜像、端口、挂载和启动配置，只加入 env_file 部分。

操作入口是项目的 compose.yaml 文件，配置路径为 services → api → env_file，文件路径为 env/api.env。Compose 的服务环境变量来自配置，不存在一个通用的“给全项目加载文件就只影响某服务”的按钮。下图采用原创文件编辑说明界面，帮助辨认配置位置，不代表某个软件的真实截图。

步骤一：在 api 节点绑定文件并保存

在你使用的文本编辑器中打开项目 compose.yaml，在 api 服务内加入 env_file 列表，注意它与 image、command 同级。随后在项目 env 目录创建 api.env，填入演示变量并保存两个文件。完整的最小演示配置如下：

# 只在 api 服务下声明文件；worker 不继承这组变量。
services:
  api:
    image: alpine
    command: ["sleep", "3600"]
    env_file:
      - ./env/api.env
  worker:
    image: alpine
    command: ["sleep", "3600"]

env/api.env 的内容：

# 仅使用非敏感演示值；密码等信息应使用 secrets。
APP_MODE=preview
FEATURE_SEARCH=true

完成后的可见状态是：文件树里有 compose.yaml 和 env/api.env，api 节点内出现 env_file，worker 节点没有该属性。此时只是保存了配置，并未证明已有容器环境已经变化。

env_file 的相对路径以 Compose 文件的位置为基准。这里的 ./env/api.env 指向与 compose.yaml 同目录下的 env 子目录，不是容器内路径，也不是把文件挂载到容器里。应用最终读取的是容器环境变量；如果应用需要读取文件本身，应另外设计挂载。

步骤二：只重建 api，并确认非敏感变量

进入 compose.yaml 所在项目目录，在现有命令行环境依次运行下面两条命令。第一条明确选中 api，使用 --no-deps 避免启动关联服务，并用 --force-recreate 重新创建目标容器；第二条读取 APP_MODE。示例镜像提供 printenv，真实业务镜像若没有该工具，应使用应用自己的非敏感配置诊断入口。

# 在 compose.yaml 所在目录运行，仅重建 api，不启动依赖。
docker compose up -d --no-deps --force-recreate api
# 在运行中的 api 中读取一个非敏感变量。
docker compose exec api printenv APP_MODE

在上述演示配置成功创建并运行后，读取 APP_MODE 应得到 preview。如果返回服务未运行、命令不存在或变量不存在，应先处理对应错误，不能把命令失败当成变量为空。本文未运行示例，图中的状态也不作为执行证据。

重建会替换目标容器，应用应把需要保留的数据放在已规划的持久化存储中。实际项目有依赖服务时，--no-deps 假定所需依赖已处于可用状态；它不会替你完成依赖准备。这里不需要执行全项目 down 来应用一个服务的环境变量变化。

为什么 .env 与 --env-file 容易造成误解

项目默认 .env 和 CLI 的 --env-file 主要参与 Compose 文件中的变量插值。服务级 env_file 则直接用于设置对应容器的环境。两者可以配合使用，但“Compose 能读取某个值”不等于“这个值已经进入容器”。应以服务配置是否明确引用为判断依据。

同一个服务同时使用 environment 和 env_file 时，environment 的同名项优先。若文件里写的是 preview，而容器里看到另一值，先查看 environment 是否覆盖，再看是否真的重建了正确项目中的 api。不要为了排查一个变量而输出全部环境变量，演示只读取 APP_MODE。

常见问题

把 env_file 放在 services 顶层可以吗？

本文要设置的是服务属性，应放在 api 内。YAML 缩进决定属性归属，不是文件名决定影响范围。worker 如果也需要这些变量，须在 worker 下独立声明。

修改 api.env 后只执行 restart 为什么看不到新值？

容器环境在创建时确定。应用新环境应按 Compose 配置重新创建目标服务容器；本文使用强制重建让这个动作明确发生。

env 文件能不能放密码？

Docker 官方建议对密码等敏感信息使用 secrets。本文文件只放非敏感演示开关，不把环境变量文件当作秘密管理系统。

多个 env 文件如何安排？

env_file 可以列出多个文件，按列表顺序处理，后面的同名值覆盖前面的值。建议先共享默认值、再服务专用值，并避免与 environment 的覆盖关系混淆。

完成时应能对应三件事：api 的 env_file 指向正确文件、api 容器已按新配置创建、APP_MODE 的非敏感读取值符合预期。其他服务是否使用同一文件，由各自的服务配置决定。

• Docker：设置容器环境变量
• Compose 服务 env_file 参考
• docker compose up 参数