切换语言

迁移到 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 始终可以通过 . 此外，默认情况下，“使用 Compose V2”设置处于开启状态，该设置提供了 中的别名。docker composedocker-compose

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

Compose V1 和 Compose V2 有什么区别？

docker-compose 与 docker compose

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

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

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

提示

将连字符 （） 替换为空格，而不是 .-docker composedocker-compose

服务容器名称

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

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

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

例如，运行 Compose 命令会生成一个使用 Compose V1 命名的容器和一个使用 Compose V2 命名的容器。-p myproject up --scale=1 svcmyproject_svc_1myproject-svc-1

提示

在 Compose V2 中，全局标志或环境变量会保留 Compose V1 的行为，以使用下划线 （） 作为单词分隔符。 由于每次运行 Compose V2 命令都必须指定此选项，因此建议您在过渡到 Compose V2 时仅将其用作临时措施。--compatibilityCOMPOSE_COMPATIBILITY_

命令行标志和子命令

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 文件插值，并包含许多示例，涵盖了一些棘手的情况，例如转义嵌套引号。

检查是否：

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

提示

在项目上运行以在 Compose V2 执行插值后预览配置 验证值是否按预期显示。docker compose config

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

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

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

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

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

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

迁移正在运行的项目

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

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

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

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

其他资源