Docker Compose config 怎么列出配置中缺少的环境变量

想在启动服务前找出 Docker Compose 配置里缺少的环境变量，可以先运行 docker compose config 做配置解析，而不是直接执行 docker compose up。它会读取 Compose 文件并展开插值；对必需变量没有值的情况，通常会在预检输出中给出变量名或警告。把变量来源、预检命令和最终修复分开看，就能快速判断是变量没提供，还是服务本身启动失败。

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

步骤一：准备一个能暴露问题的 Compose 文件

先准备两个非敏感示例变量：镜像名和数据库地址。为了让“缺失”状态明确，可以只提供其中一个，把另一个留给预检命令发现。

services:
  web:
    image: ${APP_IMAGE:?请提供 APP_IMAGE}
    environment:
      DATABASE_URL: ${DB_URL:?请提供 DB_URL}
    ports:
      - "8080:8080"

这里的 :? 是 Compose 插值语法的一部分：变量为空或未提供时，解析阶段会给出提示。示例故意使用测试镜像名和测试地址，不放真实密码。先确认文件名和服务缩进正确，后续命令才有可比较的输入。

步骤二：用 docker compose config --environment 查看可用变量

进入包含 Compose 文件的项目目录，先查看当前 Compose 进程能看到哪些环境变量。这个动作的目的不是输出全部系统环境，而是确认变量来源是否符合预期，例如当前 shell 或指定的环境文件是否已经进入解析范围。

# 在 compose.yaml 所在目录查看 Compose 当前读取到的环境变量
docker compose config --environment

# 指定项目环境文件，避免因为当前工作目录不同而读错变量来源
docker compose --env-file .env.dev config --environment

如果当前 Docker Compose 版本支持该选项，输出中可以看到变量名称与解析来源。不要把这段输出原样上传到公共日志：真实环境里可能混有凭据。更稳妥的做法是使用脱敏的开发文件，或只截取变量名做人工核对。

当输出和预期不一致时，先核对三件事：实际运行目录、Compose 文件名，以及 --env-file 的路径。它们是变量来源问题，不要先去重启容器。

步骤三：用 docker compose config 做缺失变量预检

变量来源确认后，执行配置解析。命令只负责把 Compose 文件解析成最终配置，并在必需变量缺少时暴露问题；它不会替你启动服务。

# 解析 Compose 配置并把结果写到临时文件，便于人工查看警告和展开值
docker compose config > compose.rendered.yaml

# 使用开发环境文件再次预检，确保同一套输入可重复
docker compose --env-file .env.dev config > compose.rendered.dev.yaml

重点看命令执行时的警告和退出状态。对上一步示例，如果 APP_IMAGE 有值而 DB_URL 没有值，预检结果应能把问题集中到 DB_URL，而不是让你从容器日志里猜。写入渲染文件前要确认文件不会被提交；渲染结果可能包含环境变量展开后的敏感内容。

步骤四：用 --env-file 和项目目录修正变量来源

发现缺失后，不要随意在 Compose 文件里写死值。优先建立只用于本地或 CI 的环境文件，再通过 --env-file 明确传入；如果使用多个 Compose 文件，也要固定项目目录，避免相对路径随执行位置变化。

# 用不含生产凭据的开发文件补齐插值变量
cat > .env.dev 

如果项目通过脚本调用 Compose，脚本也应显式传入同一份环境文件，而不是依赖执行者的全局 shell。这样本地、CI 和文档中的检查命令才有一致输入。完成后删除渲染文件或把它加入忽略规则。

步骤五：把预检命令保存成可重复检查

可以在项目文档或 CI 中保留一条不启动容器的检查命令。命令失败时让流水线停止，成功时再进入真正的构建或启动阶段。这里的脚本只检查配置，不打印变量值。

#!/usr/bin/env bash
set -euo pipefail

# 只做 Compose 解析，避免预检阶段启动任何容器
docker compose --env-file .env.dev config > /dev/null

# 用明确的成功提示代替输出可能含敏感值的完整渲染结果
echo "Compose 配置预检通过"

如果预检通过但服务仍然启动失败，问题就已经从“插值变量缺失”转移到了镜像、网络、端口或服务依赖等运行阶段。继续排查时保留这条边界，不要把所有错误都归因于环境变量。

常见问题

只执行 docker compose config 就会启动容器吗？

不会。它的职责是解析并展示 Compose 配置；真正启动服务的是 docker compose up 等命令。

为什么变量写在 .env 里，config 仍然提示缺失？

优先检查工作目录、文件名、变量名大小写和 --env-file 路径。还要区分 Compose 插值使用的变量和服务进程内部读取的环境变量，它们不一定来自同一个位置。

可以把 compose.rendered.yaml 提交到仓库吗？

不要默认提交。解析结果可能包含展开后的敏感值，应该使用脱敏开发变量、加入忽略规则，或只把预检命令和非敏感结果写进文档。

最终判断标准是：能明确列出 Compose 文件需要的变量，能用同一份环境文件重复完成 config 预检，并且没有把真实凭据写进渲染文件或日志。做到这三点，缺失变量问题会在启动服务前被发现。