Docker Compose 报 Additional property include is not allowed

在 compose.yaml 顶层加入 include 后，运行构建或启动命令，配置校验就停在：

(root) Additional property include is not allowed

如果实际运行的 Docker Compose 低于 2.20.0，应先处理版本不支持的问题。顶层 include 从 Compose 2.20.0 开始提供；Docker Engine 已经是 24.x，也不能说明配套的 Compose 已经支持它。

这个错误发生在配置解析阶段。修改镜像、重建容器或清理数据卷，不能让旧解析器识别新字段。应先确认报错位置和执行工具，再用只校验配置的命令验证。

三个版本号不要混着看

在原来报错的终端或 CI 执行环境中运行：

docker compose version

如果脚本实际调用的是带连字符的命令，也要单独查看：

docker-compose version

这两个入口可能指向不同安装，也可能最终使用同一个实现。不能仅凭命令中有没有空格判断功能是否可用，应以实际版本输出为准。

看到的位置	它说明什么
`docker --version` 或 Engine 版本	Docker CLI 或引擎版本，不能代替 Compose 版本
`docker compose version`	当前命令实际使用的 Compose 版本
YAML 中的 `version: '3.8'`	旧文件格式标记，不是已安装 Compose 的版本

在当前 Compose Specification 中，顶层 version 已经是兼容性字段，不能用它选择一个尚未安装的新解析器。因此，把 3.8 改成 3.9，或者删除这行，都不能给 Compose 2.18.1 增加 include 支持。

如果报错来自桌面软件、部署面板或流水线，还应确认那个执行环境中的 Compose。只升级个人电脑上的插件，不会同步升级远程执行器。

升级负责解析文件的 Compose

使用原安装渠道提供的维护版本，并确认包含 include 支持。2.20.0 是该功能的最低版本，不是今天必须安装的目标版本；文件中若还用了其他较新的字段，它们可能有更高的要求。

Docker Desktop 自带 Compose，通常随 Desktop 一起维护；Linux 上单独安装的 Compose 插件则按原来的包管理或手动安装方式更新。由其他桌面发行版捆绑的组件，应按该发行版的管理方式更新。不要为了抢占命令路径，把多套来源不明的二进制复制到不同目录。

升级后重新打开报错终端，再次查看实际版本。自动化任务也要在它自己的运行环境中检查。保留旧安装信息和原始配置，以便遇到平台兼容问题时恢复；回退到不支持 include 的工具后，也必须使用与之兼容的配置。

用两个小文件确认 include 能否解析

下面只用于配置校验。目录结构为：

project/
├── compose.yaml
└── common/
    ├── compose.yaml
    └── data/

主文件 project/compose.yaml：

include:
  - ./common/compose.yaml

services:
  app:
    image: example/app:local

被包含的 project/common/compose.yaml：

services:
  worker:
    image: example/worker:local
    volumes:
      - ./data:/data

两个镜像名都是占位值，这个示例不要求构建或拉取它们，也不要直接拿它启动业务。在 project 目录中校验：

docker compose -f compose.yaml config -q
docker compose -f compose.yaml config --services

第一条只校验配置，成功时不打印展开结果；仍需确认退出状态为成功。第二条应列出 app 和 worker，顺序不作为判断条件。如果仍报顶层 include 不允许，回到实际执行的版本与入口检查，而不是继续调整容器参数。

include 与 services 必须同为顶层字段。把它缩进到某个服务下面，是不同的结构问题；错误路径若是 services.app 而非 (root)，就不应只按低版本处理。路径拼错、被包含文件缺失，也要根据升级后出现的实际错误另行修正。

校验通过后，还要核对展开路径

用实际项目的原有 -f 参数、环境文件和项目名查看展开结果：

docker compose -f compose.yaml config

这里只展示单主文件示例。真实部署若有其他参数，核对时也要保留，避免校验了另一套配置。展开结果可能包含已替换的环境变量值，应在本机查看，不要把含凭据的输出直接发到公开渠道。

默认情况下，被 include 引入的文件按自己的所在目录解析相对路径。上述 worker 的 ./data 因此对应 project/common/data。如果使用长语法显式设置了 project_directory，则以该设置为准。

还要核对服务、卷和网络是否与主文件中的资源重名。include 不会像覆盖文件那样自动把同名资源合并成你想要的配置。服务列表完整、路径正确、资源名称无意外冲突后，再进入原有部署流程。配置校验成功不证明镜像存在、端口可用，也不证明应用能正常启动。

暂时不能升级时，不能只把 include 换成 -f

多个 -f 参数走的是合并规则，后面的文件可以覆盖或扩展前面的定义；相对路径默认统一以第一个文件为基准。include 则将文件按各自项目目录加载后引入，两者并不等价。

例如要把前面的文件改成旧工具可解析的合并形式，需要先另存兼容稿：主文件移除 include，子文件中的 ./data 改成相对主文件的 ./common/data。然后用对应的两个兼容稿校验，不能让旧工具继续读取原来的顶层 include。

这只是最简单的路径示例。真实项目还可能有构建目录、服务环境文件、绑定挂载和同名资源合并问题，应逐项对照展开结果；不要直接批量替换后部署。保留原稿，兼容稿校验失败时恢复文件即可，无需删容器或数据卷。

如果实际执行的是 docker stack deploy，本文的 Compose 插件升级路径也不能直接套用。Stack 部署使用旧的 Compose v3 文件格式，并不等同于当前 Compose Specification；应为该部署入口准备受支持的配置，而不是把 include 的最低 Compose 版本当作 Stack 的支持承诺。