Docker Compose 怎样查看多个配置文件合并后的最终配置

Docker Compose 使用多个 YAML 文件时，最容易误判的不是语法，而是“最后到底采用了哪一项配置”。实用做法是先确定基础文件，再按顺序追加覆盖文件，最后用 docker compose config 展开并查看最终模型。后一个文件可以覆盖或补充前一个文件中的同名服务配置，但文件中的相对路径仍按第一个 Compose 文件所在位置解释。

官方地址：https://docs.docker.com/reference/cli/docker/compose/config/

本文只处理一个小任务：用基础配置加开发环境覆盖配置，找出最终服务、变量和路径。健康检查、profiles 和镜像构建不在本文范围内。

先明确什么叫“最终配置”

1. 准备基础文件和环境覆盖文件

在同一个 Compose 项目中准备一个基础文件 compose.yaml，再准备一个只写开发差异的 compose.dev.yaml。基础文件放通用服务，覆盖文件只保留开发环境需要改变的字段，这样查看最终模型时更容易定位来源。

下面的示例使用一个 web 服务。代码中的注释只解释字段用途，YAML 仍保持可解析；示例没有把真实密钥写入环境变量。

# 基础文件：保存所有环境都需要的服务定义
services:
  web:
    image: example/web:stable
    ports:
      - "8080:8080"
    environment:
      APP_ENV: base
      LOG_LEVEL: info

# 开发覆盖文件：只描述开发环境要改动的字段
services:
  web:
    environment:
      APP_ENV: development
      LOG_LEVEL: debug

这两个文件没有独立的“最终文件”可供直接阅读。它们要交给 Compose 按顺序合并，接下来用命令把结果展开。

2. 按顺序指定要合并的文件

在项目根目录执行下面的命令。第一个 -f 指定基础文件，第二个 -f 指定开发覆盖文件；不要把顺序写反。

# 先读通用配置，再让开发配置覆盖同名字段
docker compose -f compose.yaml -f compose.dev.yaml config

如果只想改变本次命令的组合方式，可以继续追加其他文件；如果经常使用同一组文件，也可以通过 COMPOSE_FILE 指定文件列表。关键不在于文件数量，而在于把文件顺序写成读者和团队都能复查的固定约定。

在原创界面说明图中，左侧文件卡展示基础和覆盖两层，右侧顺序栏强调后者的覆盖位置。它帮助读者理解配置关系，不代表命令已经在本机执行。

3. 用 config 展开并核对最终模型

docker compose config 会把指定的 Compose 文件合并，并把短写法、变量和服务模型展开成更适合检查的形式。你应重点看三个区域：服务是否存在、环境变量是否已经变成开发值、路径是否仍从第一个文件的位置解析。

# 只查看展开后的配置，不启动容器
docker compose -f compose.yaml -f compose.dev.yaml config

# 只输出服务名称，适合先确认服务是否被合并进来
docker compose -f compose.yaml -f compose.dev.yaml config --services

按照上面的文件内容，最终模型中 web 服务仍保留镜像和端口，APP_ENV 与 LOG_LEVEL 应显示开发文件提供的值。这里的“应显示”是阅读配置后的预期判断，不把未实际运行的示例当成截图或执行证据。

4. 根据展开结果定位差异

如果环境变量没有变化，先检查两个文件是否写的是同一个服务名和同一个字段；如果服务消失，检查 YAML 缩进以及命令中的文件顺序。若挂载目录或 env_file 指向了意外位置，优先回到第一个 -f 文件所在目录检查相对路径，而不是只修改覆盖文件的路径。

当需要保留一份可复查结果时，可以把展开结果写入本地文件，但要注意不要把密码、Token 或生产环境变量提交到版本库：

# 把展开结果保存到临时文件，便于人工对比，不启动服务
docker compose -f compose.yaml -f compose.dev.yaml config > compose.merged.yaml

# 清理可能包含环境值的临时文件，路径请按团队规则处理
rm -f compose.merged.yaml

配置看起来“不对”时，按这张清单排查

1. 确认第一个 -f 指向真正的基础文件，后续文件才是覆盖层。
2. 确认两个文件中的服务名称完全相同，不能把 web 写成另一个名字。
3. 用 config 查看展开后的值，不要只凭覆盖文件的局部内容推断。
4. 遇到相对路径异常时，回到第一个 Compose 文件的父目录检查路径。
5. 把展开文件当作排查产物，删除其中可能出现的敏感环境值。

相关问题

多个文件是覆盖还是简单拼接？

不是简单文本拼接。Compose 会按照文件顺序合并服务模型，同名字段按规则覆盖或扩展；应使用 config 查看结果。

覆盖文件里的相对路径相对谁？

使用多文件合并时，相对路径按第一个指定的 Compose 文件解析。路径问题应先确认基础文件的位置。

记住这个闭环即可：固定基础文件、明确 -f 顺序、运行 docker compose config、按服务和路径核对最终模型。这样每次切换开发或其他环境时，都能先看清 Compose 将要采用的配置，再决定是否启动服务。