Docker Compose按环境覆盖配置文件的迁移方式

把一份能跑起来的 compose.yaml 直接复制成“开发版”和“生产版”，很快就会出现端口、镜像、环境变量到处漂移的问题。更稳的迁移方式是保留一份基础文件，再让环境文件只覆盖差异。Docker Compose 会按 -f 出现的顺序合并文件，后面的值覆盖或追加前面的值。

官方地址：https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/

先把单文件配置分成两类

迁移前不要急着改文件名。先在项目目录打开原来的 Compose 文件，把不会因环境改变的内容标成基础项：服务名、镜像构建上下文、内部网络、健康检查和容器间依赖通常属于这一类。开发端口、调试开关、挂载源码目录、生产副本数和资源限制则属于覆盖项。

在 Docker Desktop 中，进入左侧 Containers，选择当前 Compose 项目并打开项目详情。这里的项目名和服务名可以帮助你核对原文件中的 services 键；不要把容器当前状态当成配置来源，真正要迁移的是项目目录里的 YAML 文件。

按环境创建覆盖文件

在项目根目录保留 compose.yaml，再创建两个只包含差异的文件。下面的示例把开发端口映射到宿主机，把生产端口改为更明确的对外端口；基础文件里的镜像、网络和健康检查不会重复书写。

# compose.yaml：稳定项放在基础文件，所有环境都复用
services:
  web:
    image: example/web:2.4
    networks:
      - appnet
    healthcheck:
      # 用轻量探针确认服务仍能响应
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health"]
      interval: 10s
      timeout: 3s
      retries: 3

networks:
  appnet:

# compose.dev.yaml：只覆盖开发环境需要调整的字段
services:
  web:
    ports:
      - "8080:8080"
    environment:
      # 开发时打开调试，便于定位配置问题
      APP_DEBUG: "1"

生产文件可以继续使用同一个服务名：

# compose.prod.yaml：生产文件只描述生产差异
services:
  web:
    ports:
      - "80:8080"
    environment:
      # 生产关闭调试，避免把诊断信息暴露给访问者
      APP_DEBUG: "0"

文件名不必固定为 compose.override.yaml。显式使用 -f 更适合 CI 和发布脚本；命令行中的第一个文件是合并基准，覆盖文件中的相对路径也按这个基准解释。

在 Docker Desktop 中选择环境组合

先打开 Docker Desktop，进入左侧 Containers，确认旧项目已停止或已准备好回退。回到项目目录后，在项目的 Compose 操作入口选择对应环境的文件组合：开发环境选择 compose.yaml 加 compose.dev.yaml，生产环境选择 compose.yaml 加 compose.prod.yaml。如果当前 Docker Desktop 版本没有提供文件组合编辑入口，就在同一项目目录打开内置终端或系统命令行执行下面的命令，界面只负责观察结果。

# 开发环境：后一个文件覆盖基础配置
docker compose -f compose.yaml -f compose.dev.yaml up -d

# 生产环境：使用生产覆盖文件，不叠加开发覆盖
docker compose -f compose.yaml -f compose.prod.yaml up -d

回到 Docker Desktop 的项目详情，看到 web 服务为运行状态、端口映射与当前环境一致，才说明启动组合选对了。不要同时把 dev 和 prod 文件都传给命令，除非你明确想让生产文件继续覆盖开发文件；多余的 -f 会让排查变得困难。

用 config 验收最终配置

启动前先渲染最终模型，是这次迁移最有价值的一步。它能暴露服务名写错、变量未替换、端口重复以及覆盖文件路径写错等问题。

# 预览开发环境最终模型，不启动容器
docker compose -f compose.yaml -f compose.dev.yaml config

# 只检查生产环境的关键结果，可把输出保存给发布记录
docker compose -f compose.yaml -f compose.prod.yaml config > compose.prod.resolved.yaml

重点核对三处：services.web.ports 是否是目标端口，environment.APP_DEBUG 是否为预期值，以及健康检查和网络是否仍来自基础文件。数组字段不一定像标量那样简单替换，端口、挂载等内容应以 config 展开的结果为准；如果确实要清空或完全替换某个列表，再按 Compose 规范使用对应的合并标签。

常见问题与回退办法

覆盖文件里的相对路径为什么失效？

多文件合并时，相对路径以第一个 -f 文件所在目录为基准，而不是覆盖文件所在目录。把路径统一放在项目根目录，或改用适合模块化的 include，不要靠切换工作目录碰运气。

怎样确认没有误叠加开发配置？

每个环境明确写出完整的 -f 列表，并先运行同样列表的 config。生产脚本只保留基础文件和生产覆盖文件。

迁移失败如何快速回退？

保留原单文件的 Git 提交或备份，在停止当前项目后用原来的单文件命令启动。确认新组合的 config 和端口无误，再删除旧文件，避免把回退路径和新配置一起改掉。

完成迁移的判断标准不是“多了几个 YAML 文件”，而是每个环境都有可复现的 -f 组合、启动前有 config 输出、Docker Desktop 中的服务状态与端口和目标一致。这样环境差异留在覆盖层，基础服务仍只有一个来源。