遷移至 Compose V2

目錄

從 2023 年 7 月起，Compose V1 已停止接收更新。它也不再提供於 Docker Desktop 的新版本中。

Compose V2 於 2020 年首次發佈，包含在所有目前支援的 Docker Desktop 版本中。它提供了改進的 CLI 體驗、使用 BuildKit 改進的建置效能，以及持續的新功能開發。

如何切換到 Compose V2？

最簡單且建議的方式是確保您擁有最新版本的 Docker Desktop，其中包含 Docker 引擎和 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 環境變數或 --context 命令列旗標。

此變更允許您在根 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 中，全域 --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 V1Compose V2
--compatibility已棄用。根據舊版結構描述版本遷移 YAML 欄位。使用 _ 作為容器名稱的單詞分隔符，而不是 - 以匹配 V1。
ps --filter KEY-VALUE未記載。允許依任意服務屬性進行篩選。僅允許依特定屬性進行篩選，例如 --filter=status=running。

環境變數

Compose V1 中的環境變數行為沒有正式記載，並且在某些邊緣情況下行為不一致。

對於 Compose V2，環境變數 章節涵蓋了 優先順序 以及 .env 檔案插值，並包含許多涵蓋棘手情況的範例，例如逸出巢狀引號。

檢查是否

  • 您的專案使用多個層級的環境變數覆蓋，例如 .env 檔案和 --env CLI 旗標。
  • 任何 .env 檔案值都有逸出序列或巢狀引號。
  • 任何 .env 檔案值都包含文字 $ 符號。這在 PHP 專案中很常見。
  • 任何變數值都使用進階展開語法，例如 ${VAR:?error}。

提示

在專案上執行 docker compose config 以預覽 Compose V2 執行插值後的組態，以驗證值是否如預期般顯示。

通常，透過確保字面值（無插值）使用單引號，而應套用插值的數值使用雙引號，即可維持與 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 對服務容器的命名方式不同，因此在最初由 V1 啟動且服務正在執行的專案上第一次使用 V2 執行 up 命令時，將會重新建立服務容器並更新名稱。

請注意，即使使用 --compatibility 標誌來保留 V1 的命名風格，Compose 仍然需要在 V2 第一次執行 up 命令時重新建立最初由 V1 啟動的服務容器，以便遷移內部狀態。

在 Docker-in-Docker 中使用 Compose V2

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 日發布。這些套件自那時起就沒有收到任何安全性更新。使用風險自負。

其他資源