迁移到 Compose V2

从2023年7月起，Compose V1停止接收更新。它也不再包含在Docker Desktop的新版本中。

Compose V2于2020年首次发布，包含在所有当前支持的Docker Desktop版本中。它提供了改进的CLI体验、使用BuildKit改进的构建性能以及持续的新功能开发。

如何切换到Compose V2？

最简单且推荐的方法是确保您拥有最新版本的Docker Desktop，它捆绑了Docker Engine和Docker CLI平台，包括Compose V2。

使用Docker Desktop，Compose V2始终可作为docker compose访问。此外，**使用Compose V2**设置默认启用，它提供了来自docker-compose的别名。

对于Linux上的手动安装，您可以通过以下两种方式获取Compose V2：

• 使用Docker的仓库（推荐）
• 手动下载和安装

Compose V1和Compose V2之间有什么区别？

docker-compose vs docker compose

与Compose V1不同，Compose V2集成到Docker CLI平台中，推荐的命令行语法是docker compose。

Docker CLI平台提供了一组一致且可预测的选项和标志，例如DOCKER_HOST环境变量或--context命令行标志。

此更改允许您在根docker命令上使用所有共享标志。例如，docker --log-level=debug --tls compose up启用来自Docker Engine的调试日志记录，并确保对连接使用TLS。

提示

通过用空格替换连字符 (-)，使用docker compose代替docker-compose来更新使用Compose V2的脚本。

服务容器名称

Compose根据项目名称、服务名称和规模/副本数生成容器名称。

在Compose V1中，下划线 (_) 用作单词分隔符。在Compose V2中，连字符 (-) 用作单词分隔符。

下划线不是DNS主机名中的有效字符。通过使用连字符，Compose V2确保可以通过一致且可预测的主机名通过网络访问服务容器。

例如，运行Compose命令-p myproject up --scale=1 svc，Compose V1会生成名为myproject_svc_1的容器，而Compose V2会生成名为myproject-svc-1的容器。

提示

在Compose V2中，全局--compatibility标志或COMPOSE_COMPATIBILITY环境变量保留Compose V1的行为，使用下划线 (_) 作为单词分隔符。由于此选项必须为每次运行的Compose V2命令指定，因此建议您仅将其用作迁移到Compose V2时的临时措施。

命令行标志和子命令

Compose V2支持几乎所有Compose V1标志和子命令，因此在大多数情况下，它可以用作脚本中的直接替换。

V2中不支持

以下在Compose V1中已弃用，并且在Compose V2中不受支持

• docker-compose scale。请改用docker compose up --scale。
• docker-compose rm --all

V2中的不同之处

以下在Compose V1和V2中的行为有所不同

环境变量

Compose V1中环境变量的行为未正式记录，并且在某些极端情况下行为不一致。

对于Compose V2，环境变量部分涵盖了优先级以及.env文件插值，并包含许多涵盖棘手情况的示例，例如转义嵌套引号。

检查是否

• 您的项目使用了多层级的环境变量覆盖机制，例如.env文件和--env命令行参数。
• 任何.env文件的值都包含转义序列或嵌套引号。
• 任何.env文件的值都包含字面意义上的$符号。这在PHP项目中很常见。
• 任何变量值都使用了高级扩展语法，例如${VAR:?error}。

提示

在Compose V2执行插值后，运行docker compose config命令来预览项目的配置，以验证值是否如预期所示。

通常可以通过确保字面值（无插值）使用单引号，而应应用插值的变量值使用双引号来保持与Compose V1的向后兼容性。

这对使用Compose V1的项目意味着什么？

对于大多数项目，切换到Compose V2不需要更改Compose YAML文件或您的开发工作流程。

建议您采用运行Compose V2的新首选方式，即使用docker compose而不是docker-compose。这提供了额外的灵活性，并消除了对docker-compose兼容性别名的需求。

但是，为了方便起见并提高与第三方工具和脚本的兼容性，Docker Desktop继续支持将命令重定向到docker compose的docker-compose别名。

切换之前我还需要知道其他什么内容？

迁移正在运行的项目

在V1和V2中，在Compose项目上运行up命令会根据将Docker Engine中的实际状态与已解析的项目配置（包括Compose YAML、环境变量和命令行参数）进行比较，根据需要重新创建服务容器以达到所需状态。

由于Compose V1和V2以不同的方式命名服务容器，因此在使用V2第一次在具有最初由V1启动的运行服务的项目上运行up命令时，会导致服务容器以更新的名称重新创建。

请注意，即使使用--compatibility标志来保留V1的命名样式，Compose仍然需要在V2第一次运行up命令时重新创建最初由V1启动的服务容器，以迁移内部状态。

将Compose V2与Docker-in-Docker一起使用

Compose V2现在包含在Docker Hub上的Docker官方镜像中。

此外，新的Docker Hub上的docker/compose-bin镜像打包了最新版本的Compose V2，可在多阶段构建中使用。

如果需要，我还能使用Compose V1吗？

是的。您仍然可以下载并安装Compose V1软件包，但如果出现任何问题，Docker将不会提供支持。

警告

最终的Compose V1版本1.29.2发布于2021年5月10日。此后这些软件包没有收到任何安全更新。使用风险自负。

其他资源

• PyPI上的docker-compose V1
• Docker Hub上的docker/compose V1
• GitHub上的docker-compose V1源代码