在遇到 Docker Compose 相关报错时，经常看到的两个命令分别是 docker compose 和 docker-compose。前者是 Docker CLI 的插件版，后者是独立安装的 standalone 版本。两者都能启动同一份 docker-compose.yml，但安装方式、命令入口和默认解析行为并不完全一致。新项目建议直接使用插件版，存量脚本如果大量使用 docker-compose，可以先保留 standalone，但需要明确它和插件版之间的边界。

判断当前安装的是哪一种版本，最直接的方法是分别执行 `docker compose version` 和 `docker-compose version`。如果前者正常输出类似 `Docker Compose version v2.x.x` 而后者提示命令不存在，说明只有插件版；反之如果后者输出版本信息而前者报错，则只有 standalone 版。如果两条命令都能执行，说明两个版本同时存在，此时应明确优先使用插件版，避免在脚本中混用 `docker compose` 与 `docker-compose` 造成行为不一致。

安装插件版时，二进制文件必须命名为 `docker-compose`，并放置到 Docker CLI 的插件目录中，例如 `/usr/local/lib/docker/cli-plugins/` 或用户目录下的 `~/.docker/cli-plugins/`。放置后务必赋予可执行权限，可用 `install -o root -g root -m 0755 docker-compose-linux-x86_64 /usr/local/lib/docker/cli-plugins/docker-compose` 完成。常见坑是文件放对了但缺少执行权限，导致执行 `docker compose` 时提示 `exec: "docker-compose": executable file not found in $P…

两种版本先分清

插件版的二进制一般是一个名为 docker-compose 的可执行文件，放在 Docker CLI 的插件目录下，Docker 通过 docker compose 调用该文件。standalone 版是一个独立的 docker-compose 二进制，安装后直接出现在 PATH 中，通过 docker-compose 执行。即便两个版本内部都是 Compose V2 实现，插件版与 standalone 在查找配置文件和资源命名规则上也可能有差别，不能简单视为同一个命令的不同写法。

如何判断当前是哪一种

判断当前安装的是哪一种版本，最直接的方法是分别执行 docker compose version 和 docker-compose version。如果前者正常输出类似 Docker Compose version v2.x.x 而后者提示命令不存在，说明只有插件版；反之如果后者输出版本信息而前者报错，则只有 standalone 版。如果两条命令都能执行，说明两个版本同时存在，此时应明确优先使用插件版，避免在脚本中混用 docker compose 与 docker-compose 造成行为不一致。

在脚本里建议固定使用插件版命令，并先用 type docker compose 或 which docker-compose 看清各自路径。如果两条命令都存在，还可以临时对比 docker compose config 和 docker-compose config 的输出，确认当前解释器实际解析到哪个文件。

从 standalone 切换到插件版，先看引擎版本

插件版依赖 Docker 客户端与引擎的通信能力，部分新特性要求 Docker Engine 版本不能过低。升级前先运行 docker version 查看 Server 版本，若引擎太旧，插件版可能无法正常工作。standalone 版自包含编译，对引擎版本的依赖相对宽松，但也不会主动适配引擎的新接口。因此，在旧版引擎上迁移到插件版时，应提前验证 docker compose up -d 是否能成功启动现有项目，避免生产环境突然不可用。

切换前建议先保留旧版本，用 docker-compose down 清理旧资源，再启用插件版。清理后不要急着写新命令，先跑一次 docker compose config，确认服务定义、卷和网络名称与旧版本解析结果一致。不一致的地方以插件版为准，但需要在测试环境里重新验证依赖关系。

配置解析差异要优先确认

两个版本都可以读取 docker-compose.yml 和 docker-compose.override.yml，但插件版默认按 Compose V2 规范解析，支持 include、name 等新字段；standalone 若停留在 v1 代，则遇到这些字段可能忽略或直接报错。检查方法是对同一配置文件分别运行 docker compose config 和 docker-compose config，对比输出的服务定义是否一致。若出现差异，以插件版的解析结果为准，并手工修正配置文件中的非标准写法。

如果 docker-compose.yml 里还写着 version: '3' 这种字段，插件版通常不会报错，但 standalone v1 可能会把它当作关键信息。建议统一移除 version 字段，让两种解释器的行为更接近。配置文件里使用扩展字段时，要先确认插件版是否认识那些字段，特别是一些老教程里出现的 docker-compose.yml 写法。

补上权限和网络名这两个检查点

插件版安装时，二进制文件需要命名为 docker-compose，放到 Docker CLI 插件目录，例如 /usr/local/lib/docker/cli-plugins/ 或用户目录下的 ~/.docker/cli-plugins/。放置后要记得赋予可执行权限。如果文件放对了但缺少执行权限，执行 docker compose 会提示 exec: "docker-compose": executable file not found in $PATH，虽然文件就在插件目录里，但 Docker 认为它不可执行。可以用 install -o root -g root -m 0755 docker-compose-linux-x86_64 /usr/local/lib/docker/cli-plugins/docker-compose 完成安装。

另一个容易遗漏的是网络命名。插件版在创建自定义网络时，通常会给网络名加上项目前缀，standalone 在部分版本中不会。从 standalone 切到插件版后，先执行 docker network ls 检查网络列表。如果发现旧网络没有复用，而是新建了带前缀的同名网络，需要先清理旧网络，并将 compose 文件里的网络名显式声明为外部网络，避免每次重建都生成新网络。

这两个版本的区别，不在命令行里多一个短横线，而在于它们如何看待 compose 项目、如何与 Docker 引擎通信。判断当前版本、确认配置解析结果、检查网络命名，这三步做完，再决定是否切换。在旧版本上，多用 docker compose config 和 docker network ls 验证，会比直接改命令更稳。