匯出器概觀

目錄

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

  • image：將建置結果匯出到容器映像檔。
  • registry：將建置結果匯出到容器映像檔，並將其推送至指定的儲存庫。
  • local：將建置根目錄檔案系統匯出到本機目錄。
  • tar：將建置根目錄檔案系統打包到本機 tarball。
  • oci：以 OCI 映像檔佈局Docker 映像檔規格 v1.2.0使用匯出器

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

    $ 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` exporter，它的功能相同。

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

    將映像檔佈局匯出至檔案

    您可以使用 `oci` 或 `docker` exporter 將構建結果儲存到本地檔案系統的映像佈局中。這兩個 exporter 都會產生一個包含相應映像佈局的 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` exporter。

    `local` exporter 會將檔案系統解壓縮到指定位置的目錄結構中。`tar` exporter 會建立一個 tarball 封存檔。

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

    `local` exporter 在多階段構建中非常有用，因為它允許您僅匯出最少數量的構建產物，例如自包含的二進制檔案。

    僅限快取的匯出

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

    $ docker buildx build --output type=cacheonly

    如果您沒有指定 exporter，也沒有提供像 `--load` 這樣的速記選項（會自動選擇適當的 exporter），Buildx 預設會使用 `cacheonly` exporter。除非您使用 `docker` 驅動程式進行構建，否則您會使用 `docker` exporter。

    當使用 `cacheonly` 作為預設值時，Buildx 會記錄一條警告訊息。

    $ 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

    多個匯出器

    Buildx 0.13.0 版引入

    您可以透過多次指定 `--output` 旗標，為任何給定的構建使用多個 exporter。這需要 **Buildx 和 BuildKit** 版本 0.13.0 或更高版本。

    以下範例使用三個不同的 exporter 運行單個構建：

    • `registry` exporter 將映像推送到 registry。
    • `local` exporter 將構建結果提取到本地檔案系統。
    • `--load` 旗標（`image` exporter 的速記）將結果載入到本地映像儲存庫。
    $ docker buildx build \
  --output type=registry,tag=<registry>/<image> \
  --output type=local,dest=<path/to/output> \
  --load .

    設定選項

    本節說明 exporter 可用的一些組態選項。

    這裡描述的選項至少適用於兩種或多種類型的 exporter。此外，不同的 exporter 類型也支援特定的參數。有關哪些組態參數適用的更多資訊，請參閱關於每個 exporter 的詳細頁面。

    這裡描述的通用參數為：

    壓縮

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

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

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

    將 `compression-level=<value>` 選項與 `compression` 參數一起使用，為支援它的演算法選擇壓縮級別：

    • `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` exporter 會建立容器映像。這些 exporter 支援 Docker 媒體類型（預設）和 OCI 媒體類型。

    要匯出設定了 OCI 媒體類型的映像，請使用 `oci-mediatypes` 屬性。

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

    後續步驟

    閱讀關於每個 exporter 的資訊，以了解它們的工作原理和使用方法。