Docker Compose 与 docker-compose 的区别

问题描述

许多 Docker 用户在使用过程中发现了两个类似的命令：docker compose（带空格）和 docker-compose（带连字符）。这两个命令看起来很相似，但实际上代表了 Docker Compose 工具的不同版本和实现方式。

解决方案

核心区别

历史演变

Docker Compose 经历了从独立工具到 Docker CLI 插件的演变过程：

• docker-compose：最初的 Python 版本（v1）
• docker compose：新的 Go 版本（v2），作为 Docker CLI 插件

版本对比

特性	docker-compose (v1)	docker compose (v2)
实现语言	Python	Go
安装方式	独立二进制文件	Docker CLI 插件
命令格式	带连字符	带空格
配置文件偏好	docker-compose.yml	compose.yml
项目状态	已弃用	活跃开发

重要行为差异

1. 环境文件处理

docker compose 在某些情况下可能会以不同方式处理 .env 文件：

# docker-compose.yml 示例
services:
  web:
    image: nginx
    env_file:
      - ${PWD}/.env  # 注意路径解析可能不同

环境文件路径

v2 版本可能在不同位置查找 .env 文件，建议明确指定路径或重命名模板环境文件。

2. 镜像标签命名

两个版本生成镜像标签的方式不同：

# v1 使用下划线连接
myproject_web

# v2 使用连字符连接  
myproject-web

3. 网络和 DNS 解析

v2 版本改变了 /etc/hosts 文件的更新机制，使用内部 DNS 解析器（127.0.0.11）而不是直接修改 hosts 文件。

安装指南

在 Linux 上安装 v2 版本

手动安装

# 创建插件目录
mkdir -p ~/.docker/cli-plugins/

# 下载最新版本
curl -SL https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose

# 添加执行权限
chmod +x ~/.docker/cli-plugins/docker-compose

# 验证安装
docker compose version

使用包管理器

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

# CentOS/RHEL  
sudo yum install docker-compose-plugin

自动安装脚本

COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r '.tag_name')
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/$COMPOSE_VERSION/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

安装旧版 v1（不推荐）

# 仅适用于需要向后兼容的情况
VERSION=v2.12.2
curl -SL https://github.com/docker/compose/releases/download/$VERSION/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
chmod a+x /usr/local/bin/docker-compose

迁移建议

1. 测试现有配置：在切换前使用 docker compose 测试现有项目
2. 更新脚本：将脚本中的 docker-compose 改为 docker compose
3. 检查环境变量：确认环境文件路径解析正常
4. 验证网络配置：特别是依赖 hosts 文件的服务

最佳实践

• 使用 compose.yml 作为配置文件名称
• 明确指定环境文件路径而非依赖默认行为
• 定期更新到最新版本以获得安全修复和新功能

总结

docker compose（v2）是 Docker Compose 的未来方向，提供了更好的性能、更紧密的 Docker 集成和持续的更新支持。虽然与旧版 docker-compose（v1）存在一些行为差异，但迁移过程相对简单，且能获得更好的开发体验。

建议所有新项目使用 docker compose v2 版本，现有项目也逐步迁移到新版本，以享受更好的性能和后续的功能更新。