Docker Compose 启动前，可先用 docker compose config 检查文件解析、变量替换和多文件合并结果。config --quiet 通过只说明配置校验通过，不证明镜像能拉取、端口无冲突或应用健康；它不能替代部署后的业务验证。

适用版本与前提

适用于 Docker Compose V2 插件，即 docker compose 命令；不直接套用到旧版 docker-compose V1 或 docker stack deploy。先运行 docker compose version 和 docker compose config --help，确认本机支持所用选项。本文为 AI 辅助的 Docker 官方资料整理，未在目标环境实测。需要可读取的项目文件及环境文件，本文不执行 up、down 或删除数据。

一、固定文件与环境来源

docker compose version
docker compose config --help
docker compose --env-file ./config/prod.env -f compose.yaml -f compose.prod.yaml config --quiet

上述文件名为示例，换成项目实际路径，并在确定的工作目录运行。多个 -f 的顺序属于检查条件，后续部署也必须保持一致；不要检查一组文件却用另一组执行部署。config 会合并指定文件、解析变量并规范化模型，--quiet 仅校验而不打印模型。参见 docker compose config 官方说明。

二、变量错误要看来源，不只看文件内容

环境变量可能来自 shell 与环境文件。即使编辑了 prod.env，shell 中同名变量也可能影响插值。将检查命令、工作目录和变量来源一并记录；不要把 .env 插值与容器内部最终环境视为同一件事。优先级与语法见 Compose 官方变量插值指南。

对必须显式设置且不能为空的值，可在自己的 Compose 文件中采用必填表达式。例如：

services:
  web:
    image: "example/web:${APP_TAG:?APP_TAG must be set}"

该示例只展示语法，example/web 是占位镜像，不是可直接上线的应用。若 APP_TAG 未设置或为空，插值会报错；不要为了消除报错随意填入 latest。先确认实际版本选择，再重复预检。

三、按需查看解析后的模型

docker compose --env-file ./config/prod.env -f compose.yaml -f compose.prod.yaml config
docker compose --env-file ./config/prod.env -f compose.yaml -f compose.prod.yaml config --services

第一条用于人工检查展开后的服务、镜像、挂载和端口，第二条只列服务名。输出可能包含密码、令牌或内部路径，不要直接贴进公开工单、博客和代码仓库。如果要临时保存，应按组织规则限制文件权限并及时清理。

检查镜像标签是否符合发布计划、端口是否仅暴露在预期接口、挂载是否指向正确目录。配置有效并不意味着这些选择适合当前生产环境；尤其不要把测试环境的路径直接照搬上线。

四、预检通过后仍有运行边界

真正执行 up 会创建、启动容器，也可能因配置或镜像变更而停止并重建已有容器，所以不能把 up 当作无影响的校验命令。实际行为见 docker compose up 官方说明。本文仅做预检，部署应结合维护窗口、数据备份与回退安排。

上线后再验证容器状态、健康检查、日志和业务请求；这些结果须来自真实环境，不能从 config 成功推导。保留本次所用文件、版本与命令，保证预检和部署能够对应。

常见问题

没有输出是不是命令没执行？使用 --quiet 时不打印配置是预期行为，还要查看命令退出状态与错误信息。

配置检查通过但启动失败怎么办？根据实际报错继续检查镜像获取、资源、端口、挂载和应用日志；不要循环执行 down、重建或清理数据卷来碰运气。

相关阅读