Docker Compose config查看变量展开结果

如果你在 compose.yaml 里写了 ${TAG}、${PORT:-8080}，却不确定 Compose 最终拿到的是什么值，直接运行 docker compose config 就能查看解析后的规范化配置；再加上 --environment，还能看到用于变量展开的环境。

排查变量展开时，先用 docker compose --env-file ./config/.env.dev config --environment 看来源，再用 docker compose --env-file ./config/.env.dev config 看最终配置。前者回答“变量从哪里来”，后者回答“配置最后变成什么”。

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

先准备一个能看出差异的 Compose 配置

假设项目目录中有下面的文件。这里把变量放到镜像标签、端口和容器环境里，方便观察同一个变量在不同字段中的展开效果。

# compose.yaml：用变量控制镜像标签和宿主机端口
services:
  web:
    image: example/web:${IMAGE_TAG:-dev} # 未设置 IMAGE_TAG 时使用 dev
    ports:
      - "${WEB_PORT:-8080}:8080" # 左侧是宿主机端口，右侧保持容器端口
    environment:
      APP_MODE: ${APP_MODE:-local} # 给容器注入最终的运行模式

# .env：Compose 默认会在项目目录寻找它
IMAGE_TAG=staging
WEB_PORT=18080
APP_MODE=test

示例中的值只用于演示。不要把数据库密码、访问令牌等敏感信息直接放进 Compose 文件或把解析后的结果提交到代码仓库。

1. 从项目入口查看规范化配置

在项目根目录打开命令入口，选择项目文件后执行 config。它不会启动服务，而是解析 Compose 模型、合并指定的文件，并把短格式展开成更完整的配置。

# 进入包含 compose.yaml 的项目目录
cd /path/to/compose-project

# 读取默认 Compose 文件，并打印变量展开后的规范化模型
docker compose config

重点看输出中的 services.web.image、services.web.ports 和 services.web.environment。如果 .env 中是 IMAGE_TAG=staging，规范化结果里应能看到类似 example/web:staging 的值；端口也会从变量表达式变成具体映射。

2. 用 --environment 查看变量从哪里来

只看 config 输出时，你知道结果，却不一定知道取值来自 shell、显式环境文件还是项目目录的 .env。把 --environment 放在 config 后面，可以打印 Compose 用于插值的环境。

# 查看当前项目解析 Compose 变量时采用的名称和值
docker compose config --environment

# 同时指定变量文件，明确查看 dev 配置的插值环境
docker compose --env-file ./config/.env.dev config --environment

排查时按这个顺序读：先确认变量名是否出现，再确认值是否来自预期文件，最后回到 config 输出确认它被替换到了正确字段。Docker 文档给出的优先关系是：shell 环境变量优先，其次是 --env-file 指定的文件；未指定时才使用项目目录中的 .env。

3. 用 --env-file 固定环境再对比结果

如果项目同时维护开发和测试变量，建议把变量文件作为命令的一部分写清楚，而不是依赖当前目录里“碰巧存在”的 .env。

# 使用测试环境变量文件，输出该环境对应的规范化 Compose 配置
docker compose --env-file ./config/.env.test config

# 将解析结果保存为临时文件，便于和另一套环境做文本对比
docker compose --env-file ./config/.env.test config -o /tmp/compose.resolved.yaml

这里的 -o 只是保存 config 的输出，不会改变服务状态。对比时优先看镜像标签、宿主机端口、容器环境和依赖服务名称等真正受变量影响的字段。

4. 变量为空时怎样快速定位

变量没有定义且没有默认值时，Compose 会提示并把它替换为空字符串。比如镜像表达式可能变成不完整的引用，这通常比 YAML 缩进更早暴露问题。

# 先保留原始变量表达式，观察哪些地方依赖插值
docker compose config --no-interpolate

# 再打印实际插值环境，确认变量是否缺失或被同名 shell 变量覆盖
docker compose config --environment

# 最后查看解析后的最终模型，确认空值落在哪个服务字段
docker compose config

如果只想声明“必须存在”，可以在 Compose 文件中使用 ${VAR:?必须设置 VAR} 这类必需变量表达式，让缺失变量直接报错，而不是悄悄得到空字符串。需要显示字面量美元符号时使用 $$，避免 Compose 把它当成插值起点。

常见问题

为什么我改了 .env，config 结果还是旧值？

先检查当前 shell 是否已经导出了同名变量。shell 值优先于文件值；可以用 config --environment 先确认实际采用的值，或显式指定正确的 --env-file。

config 会启动容器吗？

不会。它用于解析、合并和渲染 Compose 配置。需要启动服务时才使用 up，不要把“看到解析结果”和“服务已经运行”混为一谈。

怎样确认最终检查的是哪一个 Compose 文件？

把 -f compose.yaml 或多个 -f 文件显式写进命令，并配合 config 查看合并后的模型。多个文件按命令顺序合并，后面的文件会覆盖或补充前面的配置。

最后确认

记住两个命令就够了：config --environment 用来查变量来源，config 用来查变量展开后的最终配置。遇到空值时，再加上 --no-interpolate 做一次原始表达式对照，通常能很快分清是变量来源、默认值还是 Compose 文件本身的问题。