快取儲存後端

為了確保快速建置，BuildKit 會自動將建置結果快取到其內部快取中。此外，BuildKit 也支援將建置快取匯出到外部位置，以便在未來的建置中匯入。

在 CI/CD 建置環境中，外部快取幾乎是不可或缺的。此類環境通常在執行之間幾乎沒有持久性，但將映像檔建置的執行時間保持在盡可能低仍然很重要。

預設的 docker 驅動程式支援 inline、local、registry 和 gha 快取後端，但前提是您已啟用 containerd 映像檔儲存區。其他快取後端需要您選擇不同的 驅動程式。

警告

如果您在建置過程中使用密鑰或憑證，請確保使用專用的 --secret 選項 來操作它們。使用 COPY 或 ARG 手動管理密鑰可能會導致憑證洩露。

後端

Buildx 支援以下快取儲存後端

• inline：將建置快取嵌入映像檔中。

  inline 快取會被推送至與主要輸出結果相同的位置。這僅適用於 image 匯出器。

• registry：將建置快取嵌入到單獨的映像檔中，並推送到與主要輸出不同的專用位置。

• local：將建置快取寫入檔案系統上的本機目錄。

• gha：將建置快取上傳到 GitHub Actions 快取（測試版）。

• s3：將建置快取上傳到 AWS S3 儲存貯體（尚未發布）。

• azblob：將建置快取上傳到 Azure Blob 儲存體

  要使用任何快取後端，您首先需要在建置時使用 --cache-to 選項 將其指定，以將快取匯出到您選擇的儲存後端。然後，使用 --cache-from 選項 將快取從儲存後端匯入到目前的建置中。與本機 BuildKit 快取（始終啟用）不同，所有快取儲存後端都必須明確匯出和匯入。

  使用 registry 後端，使用匯入和匯出快取的 buildx 命令範例

  $ docker buildx build --push -t <registry>/<image> \
    --cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \
    --cache-from type=registry,ref=<registry>/<cache-image>[,parameters...] .
  

  警告

  一般而言，每個快取都會寫入到某個位置。沒有任何位置可以被寫入兩次而不會覆蓋先前快取的資料。如果您想要維護多個範圍的快取（例如，每個 Git 分支一個快取），請確保您對匯出的快取使用不同的位置。

  多個快取

  BuildKit 目前僅支援 單一快取匯出器。但您可以從任意多個遠端快取匯入。例如，一種常見的模式是使用目前分支和主要分支的快取。以下範例顯示如何使用 registry 快取後端從多個位置匯入快取

  $ docker buildx build --push -t <registry>/<image> \
    --cache-to type=registry,ref=<registry>/<cache-image>:<branch> \
    --cache-from type=registry,ref=<registry>/<cache-image>:<branch> \
    --cache-from type=registry,ref=<registry>/<cache-image>:main .
  

  設定選項

  本節說明產生快取匯出時可用的一些設定選項。這裡描述的選項至少適用於兩種或多種後端類型。此外，不同的後端類型也支援特定參數。有關哪些設定參數適用的更多資訊，請參閱關於每種後端類型的詳細頁面。

  這裡描述的是常用的參數

  • 快取模式
  • 快取壓縮
  • OCI 媒體類型

  快取模式

  在產生快取輸出時，--cache-to 參數接受一個 mode 選項，用於定義要包含在匯出快取中的層級。除了 inline 快取之外，所有快取後端都支援此功能。

  模式可以設定為兩個選項之一：mode=min 或 mode=max。例如，要使用 registry 後端以 mode=max 建置快取

  $ docker buildx build --push -t <registry>/<image> \
    --cache-to type=registry,ref=<registry>/<cache-image>,mode=max \
    --cache-from type=registry,ref=<registry>/<cache-image> .
  

  此選項僅在使用 --cache-to 匯出快取時設定。匯入快取 (--cache-from) 時，會自動偵測相關參數。

  在 min 快取模式（預設）下，只有匯出到結果映像檔的層級會被快取，而在 max 快取模式下，所有層級都會被快取，即使是中間步驟的層級也會被快取。

  雖然 min 快取通常較小（這可以加快匯入/匯出時間，並降低儲存成本），但 max 快取更有可能獲得更多快取命中。根據建置的複雜性和位置，您應該嘗試兩個參數，以找到最適合您的結果。

  快取壓縮

  快取壓縮選項與匯出器壓縮選項相同。local 和 registry 快取後端都支援此功能。

  例如，要使用 zstd 壓縮來壓縮 registry 快取

  $ docker buildx build --push -t <registry>/<image> \
    --cache-to type=registry,ref=<registry>/<cache-image>,compression=zstd \
    --cache-from type=registry,ref=<registry>/<cache-image> .
  

  OCI 媒體類型

  快取 OCI 選項與匯出器 OCI 選項相同。local 和 registry 快取後端都支援這些選項。

  例如，要匯出 OCI 媒體類型快取，請使用 oci-mediatypes 屬性

  $ docker buildx build --push -t <registry>/<image> \
    --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true \
    --cache-from type=registry,ref=<registry>/<cache-image> .
  

  此屬性僅在使用 --cache-to 旗標時才有意義。擷取快取時，BuildKit 會自動偵測要使用的正確媒體類型。

  預設情況下，OCI 媒體類型會為快取映像檔產生一個映像檔索引。某些 OCI 儲存庫（例如 Amazon ECR）不支援映像檔索引媒體類型：application/vnd.oci.image.index.v1+json。如果您將快取映像檔匯出到 ECR 或任何其他不支援映像檔索引的儲存庫，請將 image-manifest 參數設定為 true，以便為快取映像檔產生單一映像檔資訊清單，而不是映像檔索引

  $ docker buildx build --push -t <registry>/<image> \
    --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true,image-manifest=true \
    --cache-from type=registry,ref=<registry>/<cache-image> .