Docker Compose 插件版与独立版功能区别及升级迁移指南

如果你正在使用 docker-compose 命令，建议逐步迁移到 docker compose 插件版，新项目直接用插件版，旧项目可以并行过渡。

先说结论：Docker Compose 插件版（docker compose）是官方推荐方向，独立版（docker-compose）已进入维护模式，迁移时注意命令格式和配置文件兼容性。

• 适合：新项目直接上插件版，旧项目渐进迁移
• 重点看：命令格式从连字符变空格，配置文件语法基本兼容
• 别忽略：同时安装两种方式可并行使用，给迁移留缓冲期

命令速用版

先确认你当前用的是哪个版本：

docker-compose `--version`
docker compose version

如果第一条有输出、第二条报错，说明你在用独立版。如果两条都有输出，说明两种方式都装了。

插件版安装（Linux）：

sudo apt-get install docker-compose-plugin

或者手动放到 CLI 插件目录：

mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

验证插件是否生效：

docker compose version

为什么会这样

Docker Compose 经历了从 V1 到 V2 的架构调整。V1 是用 Python 写的独立工具，命令是 docker-compose（带连字符），需要单独下载安装。V2 用 Go 语言重构，作为 Docker CLI 的插件集成进去，命令变成 docker compose（中间空格）。

官方从 2023 年 7 月起停止对 V1 的更新维护，新功能和修复都集中在 V2 插件版。但配置文件格式（docker-compose.yml）两个版本基本兼容，迁移成本主要在命令习惯和少量语法差异上。

安装方式决定命令格式：独立安装无论 V1 还是 V2 都用 docker-compose，插件安装只有 V2 且用 docker compose。最新版 Docker Desktop 和 Linux 官方仓库安装时会自动带上插件版。

分步处理

第一步：检查当前环境

运行以下命令确认现状：

docker-compose `--version`
docker compose version
docker info | grep -i compose

如果 docker info 里能看到 compose 插件信息，说明插件已安装。

第二步：并行安装插件版

不要急着卸载独立版，先装上插件版并行使用：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-compose-plugin

# 或者手动下载插件
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

第三步：测试命令兼容性

找个现有项目，用两种方式分别执行：

docker-compose config
docker compose config

对比输出是否一致，如果有差异记下具体字段。

第四步：更新脚本和文档

检查 CI/CD 流水线、部署脚本、团队文档里的命令，把 docker-compose 逐步改成 docker compose。可以先在测试环境改，生产环境保留旧命令。

第五步：清理独立版（可选）

确认所有场景都能用插件版后，再考虑卸载独立版：

sudo rm /usr/local/bin/docker-compose

怎么验证是否生效

插件版正常工作的几个检查点：

# 1. 命令能识别
docker compose version

# 2. 能读取配置文件
docker compose config

# 3. 能启动服务
docker compose up -d

# 4. 查看运行状态
docker compose ps

# 5. 检查容器命名（V2 用连字符分隔）
docker ps | grep 项目名

如果 docker compose ps 提示 no configuration file provided，说明当前目录没有 docker-compose.yml 或 docker-compose.yaml，需要用 -f 指定文件路径：

docker compose -f /path/to/docker-compose.yml ps

常见坑

命令混用导致困惑

同时安装两种方式时，docker-compose 和 docker compose 都能用，但团队内部要统一，避免有人用这个有人用那个。

配置文件路径问题

插件版对配置文件路径更敏感，不在当前目录时要用 -f 明确指定，否则容易报找不到配置文件的错。

容器命名差异

V1 容器名用下划线分隔（project_service_1），V2 用连字符（project-service-1），如果脚本里硬编码了容器名需要调整。

CI/CD 环境版本不一致

本地用插件版、服务器用独立版可能导致行为差异，建议在流水线里明确指定 Docker 和 Compose 版本。

旧语法兼容问题

大部分 compose 文件语法两个版本兼容，但个别字段可能有差异，迁移前用 docker compose config 先校验一遍。

参考来源

• Docker 官方文档 - Install the Compose plugin: https://docs.docker.com/compose/install/linux/
• GitHub docker/compose 仓库：https://github.com/docker/compose
• 技术文章：docker compose 和 docker-compose 的区别及使用说明
• 技术文章：Docker Compose 实战指南 - V1 vs V2 对比

原文链接：https://www.zjcp.cc/ask/9930.html