文件名的查找规则
编排命令按固定顺序查找文件：新版命名优先于旧版命名。如果同一目录里存在多个候选文件，命令会直接报错，而不是静默挑选一个。因此从旧项目迁移时，先把不再使用的候选文件删掉或移出目录，再执行命令，否则很容易把文件选择歧义误读成语法问题。
基本信息
| 查找顺序 | 新版命名优先，其次是旧版命名 |
|---|---|
| 多文件并存 | 报存在多个候选配置文件的错误 |
| 指定文件 | 用 -f 参数指定，可多次叠加 |
| 推荐做法 | 新项目统一使用新版命名 |
| 脚本建议 | 显式指定文件路径，不依赖工作目录 |
典型使用场景
- 从旧命名迁移到新命名
- 排查报错究竟是文件选择歧义还是语法错误
- 在流水线里显式指定文件路径
- 多环境通过多个文件叠加配置
- 统一团队内的文件命名规范
确认与指定
确认与指定
ls compose.yaml docker-compose.yml 2>/dev/null # 先看目录里有哪些候选文件
# 报错形态：found multiple config files with supported names
docker compose -f compose.yaml config -q # 显式指定文件并做语法校验
docker compose -f compose.yaml -f compose.prod.yaml config # 多文件叠加，后者覆盖同名项情况与处理
| 情况 | 行为 | 处理 |
|---|---|---|
| 只有一个新版命名文件 | 正常运行 | 推荐状态 |
| 只有一个旧版命名文件 | 可以运行，可能带提示 | 逐步迁移到新命名 |
| 多个候选并存 | 直接报错 | 删除或移出多余的候选文件 |
| 显式指定文件 | 忽略查找顺序 | 脚本与流水线的最佳实践 |
新项目统一使用新版命名；迁移时先删除不再使用的另一个候选文件，避免出现选择歧义。
脚本没有显式指定文件时，行为依赖当前工作目录；流水线里建议固定文件路径，避免执行目录变化导致加载不同文件。
规范建议
- 项目目录里只保留一个编排文件，备份文件放到项目之外
- 脚本与流水线统一显式指定文件，不依赖默认查找
- 多环境配置用叠加方式组织，并固定叠加顺序
- 命名规范写进项目模板，避免新旧混用