在Docker官方文档和各类技术教程中，docker-compose与docker compose两种写法频繁出现。它们看起来只差一个连字符，实际却对应两代不同的工具实现。docker-compose是早期独立的Python脚本命令，属于Compose v1；docker compose则是集成在Docker CLI中的子命令插件，属于Compose v2。这个差异不仅影响命令输入方式，还影响安装、升级、功能支持和脚本兼容性。理解二者区别，可以避免在服务器环境或CI流水线中遇到命令不存在的尴尬。
一、命令形态差异：独立脚本与CLI插件
docker-compose最初发布于2013年，使用Python编写，通过pip或系统包管理器安装，最终生成一个独立的可执行文件。例如在Linux服务器上，通常位于/usr/local/bin/docker-compose，调用时直接输入docker-compose即可。它内部通过调用Docker Engine API完成容器编排，但每次执行都需要Python运行时环境，版本升级相对繁琐。
2021年之后，Docker官方用Go语言重写了Compose，并将其作为Docker CLI的原生插件发布，命令形式变为docker compose，中间是空格而不是连字符。这意味着它不再是独立的docker-compose可执行文件，而是运行在Docker CLI主进程内部的插件。安装位置一般在~/.docker/cli-plugins或/usr/libexec/docker/cli-plugins，检查插件是否安装可用docker info查看。使用插件架构后，Compose的更新可以随Docker CLI插件独立发布，不再依赖Python环境。
两者调用时最大的区别在于命令名称：v1写作docker-compose up -d，v2写作docker compose up -d。由于Linux命令解析不同，前者是一个独立进程，后者是Docker命令的子命令。如果服务器同时安装了旧版和新版，两个命令甚至可以并存，各自维护独立的版本号。可以使用以下命令分别查看版本：
docker-compose version docker compose version
这种架构变化对初学者最大的影响是，很多较早的教程仍然使用docker-compose，但新版Docker Desktop默认只带docker compose插件，导致直接复制旧教程命令会提示找不到命令。
二、功能与性能差异：v2带来的增强
Compose v2并不是简单的命令改名，它在功能上做了不少增强。最明显的是构建能力：v2默认使用BuildKit作为镜像构建引擎，支持并行构建、缓存挂载和更高效的层缓存。旧版docker-compose虽然也能通过环境变量启用BuildKit，但需要额外配置。例如在docker-compose v1中要设置DOCKER_BUILDKIT=1才能启用，而v2默认开启。
另一个重要增强是GPU资源申请。在Compose v2中，可以在YAML里为服务声明GPU设备，简化了机器学习或图形渲染容器的编排。示例片段如下：
services:
ai-service:
image: tensorflow/tensorflow:latest-gpu
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
此外，v2支持服务依赖条件判断。例如depends_on可以设置condition: service_completed_successfully，用于等待数据库初始化完成后再启动应用。旧版只支持简单的启动顺序，无法判断容器是否真正就绪。v2还引入docker compose ls列出当前项目、docker compose cp在容器和宿主机之间复制文件、--wait等待服务稳定等特性。
性能方面，由于Go语言天然具备良好的并发能力，v2在同时启动多个容器、拉取镜像、流式输出日志时表现更好，CPU和内存占用也更低。对于拥有十几甚至几十个服务的微服务项目，v2的启动速度提升明显。官方基准测试显示，部分场景下v2的构建和启动耗时比v1减少约30%到50%。
三、配置文件兼容性与迁移方法
好消息是，docker compose v2完全兼容旧版的docker-compose.yml文件，绝大多数项目无需修改配置即可直接使用。旧文件中常见的version: '3.8'字段在v2中虽然不再强制要求，但保留也不会报错。v2会忽略version字段，因为它不再需要根据版本号切换解析逻辑。因此迁移成本主要集中在命令和脚本层面，而不是配置文件。
如果之前使用docker-compose命令管理项目，迁移到v2只需把命令中的连字符替换为空格。例如：
# 旧版命令 docker-compose -f docker-compose.yml up -d --build # 新版命令 docker compose -f docker-compose.yml up -d --build
对于经常使用旧命令的开发者，可以在shell配置文件中添加别名，实现平滑过渡。例如在~/.bashrc或~/.zshrc中加入：
alias docker-compose="docker compose"
保存后执行source ~/.bashrc即可。需要注意的是，别名在非交互式shell或部分CI系统中可能不生效，所以生产脚本最好直接使用docker compose。如果服务器上还没有v2插件，可以参考Docker官方文档安装docker-compose-plugin包，或者直接使用Docker Desktop自带的版本。
四、常见问题与版本判断
很多人在安装新版Docker后仍习惯性输入docker-compose，结果遇到docker-compose: command not found错误。排查时先确认当前Docker引擎版本和Compose插件状态。执行docker compose version，如果正常输出类似Docker Compose version v2.24.0，说明v2可用，只需改变命令写法。如果这个命令也提示未找到，则需要安装插件或升级Docker。
判断当前环境是v1还是v2，最直接的方法是看版本输出。v1输出通常为docker-compose version 1.29.2, build 5becea4c，v2输出为Docker Compose version v2.24.0-desktop.1。版本号格式差异明显：v1以1.x为主，v2以v2.x标记。另外，v2执行会显示插件路径信息，而v1只显示Python版本信息。
对于新项目，建议直接在文档和脚本中使用docker compose，因为Compose v1已经停止功能更新，官方只维护安全修复。云平台和容器编排工具也已全面转向v2。如果维护的是旧项目且暂时无法迁移，可以继续安装v1，但要有计划地向v2过渡。很多团队会先保留两个命令共存，逐步把CI脚本和运维手册更新为v2，降低切换风险。
总的来说，docker-compose与docker compose的核心区别在于架构和演进方向：前者是历史遗留的Python独立工具，后者是官方主推的Go插件。由于配置文件兼容性良好，迁移难度很小，建议尽早统一到docker compose，以获得更好的性能和持续的功能更新。
docker-composedocker compose容器编排修改时间：2026-08-23 03:51:32