docker compose up 命令默认配置文件自动查找规则详解

前言

如果你经常使用 Docker Compose 来管理多容器应用，一定会遇到这样的场景：在项目目录下直接敲 docker compose up，然后它就“神奇地”找到了你的配置文件。但如果你没指定 -f 参数，它到底是怎么找到文件的呢？

默认查找顺序

当你运行 docker compose up(注意是带空格的 V2 版本命令)而没有使用 -f 指定配置文件时，Docker Compose 会按照严格的优先级顺序在当前工作目录中自动查找以下文件：

1. compose.yaml (官方强烈推荐，最高优先级)
2. compose.yml
3. docker-compose.yaml
4. docker-compose.yml (为了兼容老项目保留)

只要找到第一个存在的文件，它就会停止查找并使用该文件。

注意：这个顺序是有先后顺序的！如果你目录里同时存在 compose.yaml 和 docker-compose.yml，Docker Compose 会优先选择 compose.yaml。

为什么推荐使用compose.yaml？

从 Docker Compose V2 开始(也就是现在集成在 Docker CLI 中的版本)，官方明确推荐使用 compose.yaml 作为默认文件名。主要原因有：

• 更简洁(去掉了多余的连字符)
• 与现代 YAML 命名规范更一致
• 避免与已弃用的旧工具 docker-compose(带连字符的独立版本)混淆
• 更好的向前兼容性：新项目统一用 compose.yaml，老项目继续支持旧名字

你可以把这当成一个“最佳实践”：新项目一律用 compose.yaml。

实际例子

假设你的项目目录结构如下：

my-app/
├── compose.yaml
├── compose.yml
├── docker-compose.yml
└── Dockerfile

执行 docker compose up 时：

• 会直接使用 compose.yaml
• 完全忽略其他同类文件

如果你删掉 compose.yaml，它才会依次尝试 compose.yml，再往后是 docker-compose.yml。

关于 Override 文件

同样的规则也适用于 override 文件(用于覆盖主配置)：

• 默认会查找 compose.override.yaml 或 compose.override.yml
• 旧格式 docker-compose.override.yml 也支持，但优先级较低

小贴士

想明确指定文件？始终使用 -f 参数，例如：

docker compose -f docker-compose.yml up

多配置文件合并？可以用多个 -f：

docker compose -f compose.yaml -f compose.prod.yaml up

检查当前使用的配置文件？运行：

docker compose config

它会显示最终合并后的配置。

总结

Docker Compose 的配置文件查找规则其实非常人性化：既保留了对老项目的兼容性，又在推动大家向更现代的命名方式迁移。

建议所有新项目立即切换到 compose.yaml，既符合官方推荐，也能避免未来可能的兼容性困扰。

下次运行 docker compose up 时，不妨检查一下你的项目里用的是哪个文件名——也许是时候重命名了呢？