Docker Compose 怎么切换 env-file 而不改 compose.yaml

Docker Compose 切换开发、测试或预发布配置时，不必反复修改 compose.yaml。把变化的值放到不同的 env-file 中，然后在 docker compose 后、具体子命令前加上 --env-file 即可。真正启动前，再用 config --environment 和 config 看一遍展开结果，能避免“文件切了但端口没变”的误判。

准备 env-file：compose.yaml 只保留变量占位符

先让 Compose 文件描述结构，把环境差异留给文件。下面的示例只需要维护一次：

services:
  web:
    image: nginx:${IMAGE_TAG} # 镜像标签由当前 env-file 决定
    ports:
      - "${APP_PORT}:80" # 宿主端口随环境切换
    profiles: ["web"] # 需要时才启用这个可选服务
    environment:
      APP_ENV: ${APP_ENV} # 传入容器的运行环境名

在项目目录准备两个文件：

# 开发环境：端口和标签只属于本文件
cat > .env.dev  .env.staging 

这里的 --env-file 是 Compose CLI 的输入；服务定义里的 env_file: 则是把变量注入容器，不能用后者替代前者来控制 image 或 ports 的插值。

切换目标环境：选项要写在子命令之前

切到预发布环境时，不改 YAML，只换命令行参数：

# --env-file 放在 compose 后、up 前；--profile 打开 web 服务
docker compose --env-file .env.staging --profile web up -d

如果同一项目需要叠加一个覆盖文件，也可以按顺序写多个 --env-file：

# 后一个文件覆盖前一个文件中的同名变量
docker compose --env-file .env.staging --env-file .env.local --profile web up -d

相对路径从执行 Compose 命令的工作目录解析。命令返回后，先看 Docker Desktop 项目页里的服务卡片、端口摘要和 profile 状态；如果仍显示开发端口，优先检查命令所在目录与文件名。

切换后检查：config 和 profile 状态要对得上

不要只凭容器“能启动”判断切换成功。先检查 Compose 读取了哪些插值变量：

# 查看 Compose 实际用于插值的变量来源和值
docker compose --env-file .env.staging config --environment

# 查看展开后的 Compose 模型，确认镜像、端口和 profile
docker compose --env-file .env.staging --profile web config

检查输出时重点看三处：IMAGE_TAG 是否为 1.27-alpine，端口是否为 18080:80，以及 web 是否已经出现在启用的服务集合中。若 shell 中已经设置了同名变量，它通常优先于文件值，可先用 unset APP_PORT IMAGE_TAG APP_ENV 排除干扰。

按 profile 拉取镜像：用 parallel 控制并发

有多个可选服务时，可以先拉取镜像，再启动项目。--parallel 是 Compose 的全局并行度选项，适合在共享网络或镜像仓库限流时主动收敛任务数：

# 只拉取 web profile，并把同时进行的任务限制为 2 个
docker compose --parallel 2 --env-file .env.staging --profile web pull

# 拉取完成后再启动同一个 profile
docker compose --env-file .env.staging --profile web up -d

常见问题有三个：第一，把 --env-file 写在 up 后面会被当作子命令参数；第二，把服务字段 env_file 当成 Compose 插值文件，导致镜像标签仍为空；第三，多个文件的顺序写反，后加载的本地覆盖文件把预发布值覆盖掉。按“文件存在—变量展开—profile 启用—服务状态”的顺序检查，定位会更快。

最终确认

只要 config --environment 显示目标 env-file，config 中的镜像和端口与目标环境一致，Docker Desktop 中的 profile 与服务状态也对应上，就可以在不修改 compose.yaml 的前提下完成环境切换。下次只需替换 --env-file 的文件名，并保留同一套核对命令。

相关问题

多个 env-file 谁覆盖谁？同一个变量在多个文件中重复定义时，后写的文件覆盖先写的文件；但 shell 中已经存在的同名变量通常优先。

为什么 env-file 切换后容器里的值没变？检查变量是否只用于 Compose 插值，还是还需要在服务的 environment 或 env_file 中显式传入容器，并确认旧容器是否需要重新创建。