Docker Compose 怎样用多个文件覆盖开发配置

开发环境经常只比基础 Compose 配置多几个端口、源码挂载和调试变量。更容易维护的做法，是把稳定服务定义留在 compose.yaml，再用一个开发覆盖文件补充差异，执行时按顺序传入多个 -f。后面的文件会覆盖或补充前面的配置，但所有相对路径仍以第一个文件为基准。

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

先把稳定配置和开发差异拆开

假设项目目录如下，基础文件只描述服务之间的关系，开发文件再打开宿主机端口并挂载源码：

project/
├── compose.yaml
├── compose.dev.yaml
└── web/
    └── src/

基础文件可以保持简洁：

services:
  web:
    image: example/web:1.0
    depends_on:
      - db
  db:
    image: postgres:18
    environment:
      # 基础文件只保留稳定的数据库服务配置
      POSTGRES_DB: app

开发文件只写需要改变的部分：

services:
  web:
    # 开发环境从源码构建并挂载本地目录
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./web:/workspace/web
    environment:
      # 只覆盖开发环境需要变化的变量
      DEBUG: "1"

按顺序指定文件，后一个文件负责覆盖

在项目根目录执行下面的命令：

# 先读取稳定服务定义，再叠加开发环境差异
docker compose -f compose.yaml -f compose.dev.yaml up -d

这里的顺序不能随意交换。Compose 先读取 compose.yaml，再读取 compose.dev.yaml；后者可以给已有的 web 服务增加 build、端口、挂载和环境变量，也可以定义基础文件中没有的新服务。如果项目一直使用默认文件名 compose.yaml 和 compose.override.yaml，直接执行 docker compose up 也会自动读取默认覆盖文件。

如果开发文件名称不同，环境变量也可以表达同一组文件：

# 让当前 shell 固定使用基础文件和开发覆盖文件
export COMPOSE_FILE=compose.yaml:compose.dev.yaml
# 使用已经合并的配置启动服务
docker compose up -d

在 Windows shell 中，COMPOSE_FILE 的文件分隔符按 Docker Compose 当前环境规则设置；为了让团队脚本更直观，项目文档通常直接保留多个 -f 参数。

字段不是都按同一种方式合并

排查“为什么覆盖后仍然有旧值”时，先按字段类型判断：

例如，基础文件中的 DEBUG: "0" 会被开发文件的 DEBUG: "1" 替换；但基础文件已有的其他环境变量仍会保留。挂载项则要看容器内路径，两个来源都挂到 /workspace/web 时，开发文件的来源会成为最终值。

启动前用 config 看最终配置

只看 compose.dev.yaml 很容易误以为它是完整配置。更稳妥的做法是先让 Compose 展开文件并输出合并结果：

# 展开同一组文件，确认最终服务、端口、环境变量和挂载
docker compose -f compose.yaml -f compose.dev.yaml config

重点看四个位置：web.build 是否出现、web.ports 是否包含开发端口、web.environment.DEBUG 是否为 1，以及 web.volumes 的宿主机路径是否指向项目根目录下的 web。确认后再执行 up，能把大部分“文件写对了但启动结果不对”的问题提前暴露。

相对路径是多文件配置里最容易踩的坑

Compose 多文件合并时，build 上下文、env_file、绑定挂载等相对路径，都相对于第一个文件，也就是本例的 compose.yaml。如果 compose.dev.yaml 放在 config/ 目录，里面的 ./web 也不会自动变成 config/web。

因此，覆盖文件最好只保存服务差异，路径统一按照基础文件所在目录书写。若多个 Compose 文件分散在不同组件目录，并且确实需要每个文件按自身目录解析相对路径，可以研究 Compose 的 include 顶层元素；这和用多个 -f 做覆盖是两套语义，不要混用后再猜路径。

常见问题

为什么交换两个 -f 参数后结果变了？

因为文件按命令行顺序合并，后一个文件的值会覆盖或补充前一个文件。把基础文件放在前面、环境差异放在后面，结果才符合覆盖语义。

覆盖文件中的 ./web 为什么找不到？

多文件合并时相对路径以第一个 Compose 文件为基准，而不是以覆盖文件自身目录为基准。先检查第一个 -f 的文件位置，再用 docker compose ... config 查看展开后的路径。

怎样确认开发配置没有误带基础端口？

启动前执行同样的 docker compose -f ... config，直接查看最终 ports 列表。列表型字段可能追加，不要只凭覆盖文件里写了什么来判断。