匯出器概述

目錄

匯出器將您的構建結果儲存到指定的輸出型別。您可以使用 --output CLI 選項指定要使用的匯出器。Buildx 支援以下匯出器

  • image：將構建結果匯出為容器映象。
  • registry：將構建結果匯出為容器映象，並將其推送到指定的登錄檔。
  • local：將構建根檔案系統匯出到本地目錄。
  • tar：將構建根檔案系統打包成一個本地 tarball。
  • oci：將構建結果以 OCI 映象佈局 格式匯出到本地檔案系統。
  • docker：將構建結果以 Docker 映象規範 v1.2.0 格式匯出到本地檔案系統。
  • cacheonly：不匯出構建輸出，但執行構建並建立快取。

使用匯出器

要指定匯出器，請使用以下命令語法

$ docker buildx build --tag <registry>/<image> \
  --output type=<TYPE> .

大多數常見的用例不需要您明確指定要使用哪個匯出器。只有當您打算自定義輸出或希望將其儲存到磁碟時，才需要指定匯出器。--load 和 --push 選項允許 Buildx 推斷要使用的匯出器設定。

例如，如果您將 --push 選項與 --tag 結合使用，Buildx 會自動使用 image 匯出器，並配置該匯出器將結果推送到指定的登錄檔。

要充分利用 BuildKit 提供的各種匯出器的靈活性，您可以使用 --output 標誌來配置匯出器選項。

用例

每種匯出器型別都適用於不同的用例。以下部分描述了一些常見場景，以及如何使用匯出器生成您需要的輸出。

載入到映象儲存

Buildx 通常用於構建可以載入到映象儲存的容器映象。這就是 docker 匯出器的用武之地。以下示例展示瞭如何使用 docker 匯出器構建映象，並使用 --output 選項將該映象載入到本地映象儲存

$ docker buildx build \
  --output type=docker,name=<registry>/<image> .

如果您提供 --tag 和 --load 選項，Buildx CLI 將自動使用 docker 匯出器並將其載入到映象儲存中

$ docker buildx build --tag <registry>/<image> --load .

使用 docker 驅動程式構建的映象會自動載入到本地映象儲存中。

載入到映象儲存的映象在構建完成後即可立即用於 docker run，並且在執行 docker images 命令時，您將在映象列表中看到它們。

推送到登錄檔

要將構建的映象推送到容器登錄檔，您可以使用 registry 或 image 匯出器。

當您將 --push 選項傳遞給 Buildx CLI 時，您指示 BuildKit 將構建的映象推送到指定的登錄檔

$ docker buildx build --tag <registry>/<image> --push .

在底層，這使用了 image 匯出器，並設定了 push 引數。這與使用 --output 選項的以下長格式命令相同

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true .

您也可以使用 registry 匯出器，它的功能相同

$ docker buildx build \
  --output type=registry,name=<registry>/<image> .

將映象佈局匯出到檔案

您可以使用 oci 或 docker 匯出器將構建結果儲存到本地檔案系統上的映象佈局。這兩個匯出器都會生成一個包含相應映象佈局的 tar 歸檔檔案。dest 引數定義了 tarball 的目標輸出路徑。

$ docker buildx build --output type=oci,dest=./image.tar .
[+] Building 0.8s (7/7) FINISHED
 ...
 => exporting to oci image format                                                                     0.0s
 => exporting layers                                                                                  0.0s
 => exporting manifest sha256:c1ef01a0a0ef94a7064d5cbce408075730410060e253ff8525d1e5f7e27bc900        0.0s
 => exporting config sha256:eadab326c1866dd247efb52cb715ba742bd0f05b6a205439f107cf91b3abc853          0.0s
 => sending tarball                                                                                   0.0s
$ mkdir -p out && tar -C out -xf ./image.tar
$ tree out
out
├── blobs
│   └── sha256
│       ├── 9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e
│       ├── c78795f3c329dbbbfb14d0d32288dea25c3cd12f31bd0213be694332a70c7f13
│       ├── d1cf38078fa218d15715e2afcf71588ee482352d697532cf316626164699a0e2
│       ├── e84fa1df52d2abdfac52165755d5d1c7621d74eda8e12881f6b0d38a36e01775
│       └── fe9e23793a27fe30374308988283d40047628c73f91f577432a0d05ab0160de7
├── index.json
├── manifest.json
└── oci-layout

匯出檔案系統

如果您不想從構建結果構建映象，而是匯出已構建的檔案系統，則可以使用 local 和 tar 匯出器。

local 匯出器將檔案系統解壓到指定位置的目錄結構中。tar 匯出器建立 tarball 歸檔檔案。

$ docker buildx build --output type=local,dest=<path/to/output> .

local 匯出器在多階段構建中非常有用，因為它允許您僅匯出最少量的構建工件，例如獨立二進位制檔案。

僅快取匯出

如果您只想執行構建而不匯出任何輸出，則可以使用 cacheonly 匯出器。例如，如果您想執行測試構建，或者如果您想先執行構建，然後使用後續命令建立匯出，這會很有用。cacheonly 匯出器會建立構建快取，因此任何後續構建都會立即完成。

$ docker buildx build --output type=cacheonly

如果您未指定匯出器，並且未提供諸如 --load 等自動選擇相應匯出器的簡寫選項，則 Buildx 預設使用 cacheonly 匯出器。除非您使用 docker 驅動程式進行構建，在這種情況下您將使用 docker 匯出器。

Buildx 在預設使用 cacheonly 時會記錄警告訊息

$ docker buildx build .
WARNING: No output specified with docker-container driver.
         Build result will only remain in the build cache.
         To push result image into registry use --push or
         to load image into docker use --load

多個匯出器

要求： Docker Buildx 0.13.0 及更高版本

您可以透過多次指定 --output 標誌來為任何給定構建使用多個匯出器。這需要 **Buildx 和 BuildKit** 版本 0.13.0 或更高版本。

以下示例執行一個構建，使用三個不同的匯出器

  • registry 匯出器用於將映象推送到登錄檔
  • local 匯出器用於將構建結果提取到本地檔案系統
  • --load 標誌（image 匯出器的簡寫）用於將結果載入到本地映象儲存。
$ docker buildx build \
  --output type=registry,tag=<registry>/<image> \
  --output type=local,dest=<path/to/output> \
  --load .

配置選項

本節介紹匯出器的一些配置選項。

此處描述的選項至少適用於兩種或更多匯出器型別。此外，不同的匯出器型別也支援特定的引數。有關哪些配置引數適用的更多資訊，請參閱每個匯出器的詳細頁面。

此處描述的常見引數是

壓縮

當您匯出壓縮輸出時，您可以配置要使用的確切壓縮演算法和級別。雖然預設值提供了良好的開箱即用體驗，但您可以調整引數以最佳化儲存與計算成本。更改壓縮引數可以減少所需的儲存空間，並縮短映象下載時間，但會增加構建時間。

要選擇壓縮演算法，您可以使用 compression 選項。例如，要使用 compression=zstd 構建一個 image

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,compression=zstd .

在支援壓縮級別的演算法中，配合 compression 引數使用 compression-level=<value> 選項來選擇壓縮級別

  • gzip 和 estargz 為 0-9
  • zstd 為 0-22

一般來說，數字越高，生成的檔案越小，壓縮所需的時間也越長。

使用 force-compression=true 選項可在請求的壓縮演算法與先前壓縮演算法不同時，強制重新壓縮從先前映象匯入的層。

注意

gzip 和 estargz 壓縮方法使用 compress/gzip 包，而 zstd 使用 github.com/klauspost/compress/zstd 包。

OCI 媒體型別

image、registry、oci 和 docker 匯出器會建立容器映象。這些匯出器支援 Docker 媒體型別（預設）和 OCI 媒體型別

要匯出包含 OCI 媒體型別集的映象，請使用 oci-mediatypes 屬性。

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .

接下來做什麼

閱讀每個匯出器，瞭解它們的工作原理以及如何使用它們