Docker Desktop 怎么切换 Compose 项目的环境变量文件

在 Docker Desktop 里切换 Compose 项目的环境变量文件，核心动作不是去设置页找一个“当前 env 文件”，而是在启动 Compose 时明确传入 --env-file。例如把开发环境切到测试环境：

# 选择测试环境文件，并在后台重建 Compose 服务
docker compose --env-file ./config/.env.test up -d

但要先分清两个容易混淆的概念：--env-file主要给 compose.yaml 做变量插值；服务定义里的 env_file 才是把变量放进容器环境。Docker Desktop 负责运行本机的 Docker 引擎，切换动作由 Compose CLI 完成。

最稳的顺序是：准备环境文件，先用 config 预览解析结果，再执行 up -d，最后进入容器核对关键变量。这样即使文件名切换成功，也不会把“Compose 配置里的变量”和“容器里的变量”混为一谈。

先把两类环境变量文件分开

假设项目结构如下，Compose 文件只保存服务拓扑，环境值放到 config 目录：

shop-demo/
├── compose.yaml
└── config/
    ├── .env.dev
    └── .env.test

.env.dev 和 .env.test 可以分别写不同的镜像标签和端口：

# 开发环境：使用本地调试端口和开发标签
IMAGE_TAG=dev
API_PORT=8080

# 测试环境：使用候选版本和测试端口
IMAGE_TAG=staging
API_PORT=8081

在 compose.yaml 中引用这些值，并用 env_file 明确哪些值真正进入容器：

services:
  web:
    image: "webapp:${IMAGE_TAG}" # 镜像标签来自 --env-file 的插值
    ports:
      - "${API_PORT}:8080" # 宿主机端口也由所选环境文件决定
    env_file:
      - ./config/runtime.env # 运行时变量文件相对 compose.yaml 解析
  db:
    image: "postgres:16" # 数据库版本固定，避免随环境文件漂移

如果只在命令中传入 IMAGE_TAG，它可以替换 Compose 文件中的占位符，但不会自动成为 web 容器里的环境变量。要让容器看到它，应在 environment 中显式引用，或把它写进服务的 env_file。

用 --env-file 切换 Docker Desktop 项目

打开项目目录的终端，执行下面的命令。Docker Desktop 已启动时，Compose 会把请求交给本机 Docker 引擎：

# 先预览测试环境会生成什么配置，不创建容器
docker compose --env-file ./config/.env.test config

# 确认无误后，用同一份环境文件启动或重建服务
docker compose --env-file ./config/.env.test up -d

官方文档说明，不传 --env-file 时，Compose 会按项目目录规则寻找默认 .env；显式传入后，指定文件会覆盖默认文件的路径。相对路径是相对于执行 Compose 命令的当前目录，因此从父目录执行时应写对路径，或配合 -f 指定 Compose 文件。

如果想叠加基础值和覆盖值，可以按顺序传多个文件，后面的文件覆盖前面的同名键：

# 基础配置先读入，测试覆盖文件后读入
docker compose --env-file ./config/.env \
  --env-file ./config/.env.test config

图形界面里的项目名称、服务状态和日志仍然可以在 Docker Desktop 中查看，但“选用哪套变量文件”应保留在命令或脚本里，方便团队复现。

先预览解析结果，再检查容器状态

排查环境文件时，先检查 Compose 使用了哪些变量：

# 输出 Compose 用于插值的变量，便于发现文件或 shell 覆盖
docker compose --env-file ./config/.env.test config --environment

# 输出合并、插值后的最终 Compose 模型
docker compose --env-file ./config/.env.test config

第一条命令适合确认 IMAGE_TAG、API_PORT 来自哪里；第二条命令适合确认最终镜像名、端口映射和服务配置。预览中出现 webapp:staging 与 8081:8080 后，再执行 up -d。

如果要确认变量真的进入了容器，可只查看变量名或非敏感值：

# 只核对非敏感变量；不要把密码、令牌打印到日志
docker compose --env-file ./config/.env.test exec web printenv API_PORT

# 查看服务是否按新配置重新创建
docker compose ps

若仍看到旧值，常见原因是服务配置使用了另一个 env_file，或者变量被 environment 显式值覆盖。Compose 的容器环境优先级不是“最后看到的文件一定胜出”：命令行临时值、插值后的 environment、直接写入的 environment、服务 env_file 和镜像中的 ENV 都有明确层级。

切换失败时按这几项回退

1. 文件找不到：先运行 pwd，再确认 ./config/.env.test 是相对当前目录，而不是相对 Docker Desktop 的安装目录。
2. 值没有变化：执行 env | grep IMAGE_TAG 检查 shell 是否已有同名变量；必要时取消导出后重新运行。
3. 预览变了但容器没变：执行 docker compose up -d --force-recreate，让服务按新配置重新创建。
4. 插值正常但容器内为空：检查服务是否在 environment 或 env_file 中声明该变量，--env-file本身不是容器注入开关。
5. 敏感配置：不要把密码和令牌提交进仓库；Docker 官方建议敏感信息优先使用 secrets，并在日志核对时只输出非敏感变量。

相关问题

Docker Desktop 里有没有直接选择 .env.test 的按钮？

本文这条 Compose 工作流不依赖某个图形按钮。最可复现的方式是在项目目录执行 docker compose --env-file ...，Docker Desktop 会展示该项目和容器状态。

--env-file 和 env_file 是不是同一个东西？

不是。前者改变 Compose 文件插值时读取的文件，后者写在服务下，用于把变量传进容器；同名变量还要继续遵守 Compose 的优先级。

修改 env 文件后为什么页面上的服务没变化？

修改文件不会自动重建已存在的容器。先用 config 看解析结果，再执行 up -d，必要时加 --force-recreate。

最后确认一遍切换链路

把环境文件选择写进启动命令或脚本：先用 config --environment 看 Compose 读到什么，再用 config 看最终模型，最后用 up -d 重建并核对非敏感变量。这样 Docker Desktop 负责稳定运行项目，环境文件的切换、审查和回退都留在可追踪的 Compose 命令里。

参考：Docker Compose 环境变量、变量插值与 --env-file、环境变量优先级。