docker compose up 命令默认配置文件自动查找规则详解
<div id="navCategory"><h5 class="catalogue">目录</h5><ul class="first_class_ul"><li><a href="#_label0">前言</a></li><li><a href="#_label1">默认查找顺序</a></li><li><a href="#_label2">为什么推荐使用compose.yaml？</a></li><li><a href="#_label3">实际例子</a></li><li><a href="#_label4">关于 Override 文件</a></li><li><a href="#_label5">小贴士</a></li><li><a href="#_label6">总结</a></li></ul></div><p class="maodian"><a name="_label0"></a></p><h2>前言</h2><p>如果你经常使用 Docker Compose 来管理多容器应用，一定会遇到这样的场景：在项目目录下直接敲 <code>docker compose up</code>，然后它就“神奇地”找到了你的配置文件。但如果你没指定 <code>-f</code> 参数，它到底是怎么找到文件的呢？</p>
<p class="maodian"><a name="_label1"></a></p><h2>默认查找顺序</h2>
<p>当你运行 <code>docker compose up</code>(注意是带空格的 V2 版本命令)而<strong>没有使用 <code>-f</code> 指定配置文件</strong>时，Docker Compose 会按照<strong>严格的优先级顺序</strong>在当前工作目录中自动查找以下文件：</p>
<ol><li><code>compose.yaml</code> (<strong>官方强烈推荐</strong>，最高优先级)</li><li><code>compose.yml</code></li><li><code>docker-compose.yaml</code></li><li><code>docker-compose.yml</code> (为了兼容老项目保留)</li></ol>
<p>只要找到第一个存在的文件，它就会停止查找并使用该文件。</p>
<blockquote><p>注意：这个顺序是<strong>有先后顺序的</strong>！如果你目录里同时存在 <code>compose.yaml</code> 和 <code>docker-compose.yml</code>，Docker Compose 会优先选择 <code>compose.yaml</code>。</p></blockquote>
<p class="maodian"><a name="_label2"></a></p><h2>为什么推荐使用compose.yaml？</h2>
<p>从 Docker Compose V2 开始(也就是现在集成在 Docker CLI 中的版本)，官方明确推荐使用 <code>compose.yaml</code> 作为默认文件名。主要原因有：</p>
<ul><li>更简洁(去掉了多余的连字符)</li><li>与现代 YAML 命名规范更一致</li><li>避免与已弃用的旧工具 <code>docker-compose</code>(带连字符的独立版本)混淆</li><li>更好的向前兼容性：新项目统一用 <code>compose.yaml</code>，老项目继续支持旧名字</li></ul>
<p>你可以把这当成一个“最佳实践”：新项目一律用 <code>compose.yaml</code>。</p>
<p class="maodian"><a name="_label3"></a></p><h2>实际例子</h2>
<p>假设你的项目目录结构如下：</p>
<div class="jb51code"><pre class="brush:yaml;">my-app/
├── compose.yaml
├── compose.yml
├── docker-compose.yml
└── Dockerfile</pre></div>
<p>执行 <code>docker compose up</code> 时：</p>
<ul><li>会直接使用 <code>compose.yaml</code></li><li>完全忽略其他同类文件</li></ul>
<p>如果你删掉 <code>compose.yaml</code>，它才会依次尝试 <code>compose.yml</code>，再往后是 <code>docker-compose.yml</code>。</p>
<p class="maodian"><a name="_label4"></a></p><h2>关于 Override 文件</h2>
<p>同样的规则也适用于 override 文件(用于覆盖主配置)：</p>
<ul><li>默认会查找 <code>compose.override.yaml</code> 或 <code>compose.override.yml</code></li><li>旧格式 <code>docker-compose.override.yml</code> 也支持，但优先级较低</li></ul>
<p class="maodian"><a name="_label5"></a></p><h2>小贴士</h2>
<p>想明确指定文件？始终使用 <code>-f</code> 参数，例如：</p>
<div class="jb51code"><pre class="brush:bash;">docker compose -f docker-compose.yml up</pre></div>
<p>多配置文件合并？可以用多个 <code>-f</code>：</p>
<div class="jb51code"><pre class="brush:bash;">docker compose -f compose.yaml -f compose.prod.yaml up</pre></div>
<p>检查当前使用的配置文件？运行：</p>
<div class="jb51code"><pre class="brush:bash;">docker compose config</pre></div>
<p>它会显示最终合并后的配置。</p>
<p class="maodian"><a name="_label6"></a></p><h2>总结</h2>
<p>Docker Compose 的配置文件查找规则其实非常人性化：既保留了对老项目的兼容性，又在推动大家向更现代的命名方式迁移。</p>
<p>建议所有新项目立即切换到 <code>compose.yaml</code>，既符合官方推荐，也能避免未来可能的兼容性困扰。</p>
<p>下次运行 <code>docker compose up</code> 时，不妨检查一下你的项目里用的是哪个文件名——也许是时候重命名了呢？</p> 感谢楼主的详细分享！这个知识点真的很实用，之前一直好奇为什么不指定-f参数也能自动找到配置文件，原来是这么回事。
学到新东西了：
以前一直以为docker-compose.yml是官方标准，没想到现在compose.yaml才是正统。看来得把老项目的配置文件都改过来了。
有个小问题想请教一下：
如果项目里同时存在compose.yaml和docker-compose.yml，docker compose会优先用compose.yaml。那如果在生产环境用docker-compose（旧版本命令）的话，它会怎么选择呢？会不会有冲突？
另外还想补充一个小技巧：
除了用docker compose config查看当前配置，还可以用：
docker compose convert
这个命令可以把配置输出成标准的docker-compose.yml格式，有时候用来做版本迁移挺方便的。
总之感谢楼主的科普帖，收藏了！希望以后能多分享一些Docker Compose的实用技巧~
支持一下
頁:
[1]