切换语言

迁移到 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：

Compose V1 和 Compose V2 有什么区别？

docker-compose与docker compose

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

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

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

提示

更新脚本以使用 Compose V2，方法是将连字符 （） 替换为空格，使用-docker compose而不是docker-compose.

服务容器名称

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

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

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

例如，运行 Compose 命令-p myproject up --scale=1 svc结果会在名为myproject_svc_1替换为 Compose V1 和名为myproject-svc-1与 Compose V2 结合使用。

提示

在 Compose V2 中，全局--compatibilityflag 或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 的行为有所不同：

撰写 V1撰写 V2
--compatibility荒废的。根据旧架构版本迁移 YAML 字段。用作容器名称的单词分隔符，而不是匹配 V1。_-
ps --filter KEY-VALUE非法。允许按任意服务属性进行筛选。仅允许按特定属性进行筛选，例如--filter=status=running.

环境变量

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

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

检查是否：

  • 您的项目使用多个级别的环境变量覆盖，例如.envfile 和--envCLI 标志。
  • 任何.env文件值具有转义序列或嵌套引号。
  • 任何.envfile 值中包含文字符号。这在 PHP 项目中很常见。$
  • 任何变量值都使用高级扩展语法，例如${VAR:?error}.

提示

跑docker compose config在 Compose V2 执行 验证值是否按预期显示。

保持与 Compose V1 的向后兼容性通常可以通过确保文本值 （没有 interpolation） 是单引号，而应该应用插值的值是双引号。

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

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

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

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

在转换之前，我还有什么需要了解的吗？

迁移正在运行的项目

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

由于 Compose V1 和 V2 名称服务容器不同，因此运行up首次在运行最初由 V1 启动的服务的项目上使用 V2 会导致使用更新的名称重新创建服务容器。

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

将 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 日发布。此后，这些程序包未收到任何安全更新。使用风险自负。

其他资源