导出器概述
导出器将构建结果保存到指定的输出类型。你可以使用 --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 推断要使用的导出器设置。
例如,如果你在使用 --tag
的情况下使用 --push
选项,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=tar,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
多个导出器
你可以对任何给定构建使用多个导出器,方法是多次指定 --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-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
导出器创建容器镜像。这些导出器同时支持 Docker 媒体类型(默认)和 OCI 媒体类型。
要导出使用 OCI 媒体类型的镜像,请使用 oci-mediatypes
属性。
$ docker buildx build \
--output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .
下一步
阅读有关每个导出器的说明,了解它们的工作原理以及如何使用它们。