【AI 总结】Docker Buildx Build

docker buildx build | AI 总结

类别	内容
功能描述	使用 BuildKit 启动 Docker 镜像构建流程，支持多平台构建、缓存优化、隐私保护（如密钥管理）等增强功能
基本用法	docker buildx build [OPTIONS] PATH | URL | -
命令别名	包含 docker build、docker builder build、docker image build、docker buildx b，可简化输入

基础配置类

选项	功能	示例
-f, --file	指定 Dockerfile 路径（默认使用构建上下文根目录的 Dockerfile），支持从标准输入读取（用 - 表示）	docker buildx build -f ./custom.Dockerfile .、 cat Dockerfile | docker buildx build -f - .
-t, --tag	为构建结果镜像添加标签（格式：[registry/]repository[:tag]），支持多标签	docker buildx build -t myrepo/image:v1 -t myrepo/image:latest .
--target	指定多阶段构建的目标阶段，跳过目标阶段后的指令	若 Dockerfile 有 AS build-env 阶段，可执行 docker buildx build --target build-env .
--platform	设置目标构建平台（格式：os/arch 或 os/arch/variant），支持多平台（用逗号分隔）	docker buildx build --platform linux/amd64,linux/arm64 .

缓存优化类

选项	功能	示例
--cache-from	从外部源导入缓存（支持 registry、local、gha、s3、azblob 类型）	docker buildx build --cache-from type=local,src=./cache .
--cache-to	将构建缓存导出到外部目标（支持类型同 --cache-from，含 inline 类型（写入镜像配置））	docker buildx build --cache-to type=registry,ref=myrepo/image:cache .
--no-cache	完全不使用缓存构建	docker buildx build --no-cache .
--no-cache-filter	仅忽略指定阶段的缓存（多阶段用逗号分隔阶段名）	docker buildx build --no-cache-filter stage1,stage2 .

安全与隐私类

选项	功能	示例
--secret	向构建过程暴露密钥（支持 type=file（文件源）和 type=env（环境变量源）），避免密钥写入镜像	从文件导入：docker buildx build --secret id=aws,src=~/.aws/credentials .；从环境变量导入：SECRET_TOKEN=xxx docker buildx build --secret id=SECRET_TOKEN .
--ssh	暴露 SSH 代理 socket 或密钥，用于构建中访问私有资源（如 Git 仓库）	eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa && docker buildx build --ssh default=$SSH_AUTH_SOCK .
--allow	允许特权权限（如 network.host（主机网络）、security.insecure（无沙箱）、device（CDI 设备访问）），需配合 BuildKit 配置	docker buildx create --buildkitd-flags '--allow-insecure-entitlement security.insecure' && docker buildx build --allow security.insecure .

输出与 attestation（证明）类

选项	功能	示例
-o, --output	配置构建结果导出目标（支持 local（本地目录）、tar（压缩包）、oci（OCI 镜像格式）、docker（Docker 镜像格式）、registry（推送仓库））	推送到仓库：docker buildx build -o type=registry -t myrepo/image .；导出到本地目录：docker buildx build -o ./output .
--push	简写 --output=type=registry，自动将构建结果推送到镜像仓库	docker buildx build --push -t myrepo/image:v1 .
--load	简写 --output=type=docker，将单平台构建结果加载到本地 docker images 列表	docker buildx build --load -t myrepo/image .
--attest	生成镜像证明（支持 type=sbom（软件物料清单）、type=provenance（SLSA 溯源信息）），增强镜像可追溯性	生成 SBOM：docker buildx build --attest type=sbom .；生成溯源信息：docker buildx build --attest type=provenance .
--sbom	简写 --attest=type=sbom，快速生成 SBOM 证明	docker buildx build --sbom .
--provenance	简写 --attest=type=provenance，快速生成溯源证明，支持布尔值启用 / 禁用	docker buildx build --provenance=true .（启用）、docker buildx build --provenance=false .（禁用）
--metadata-file	将构建元数据（如镜像摘要、创建时间）写入指定 JSON 文件	docker buildx build --metadata-file metadata.json .

其他实用选项

选项	功能	示例
--build-arg	设置构建时变量（对应 Dockerfile 中的 ARG 指令），支持传递本地环境变量值	docker buildx build --build-arg HTTP_PROXY=http://xxx --build-arg GO_VERSION=1.22 .
--build-context	添加额外构建上下文（支持本地目录、OCI 目录、容器镜像、Git/HTTP URL），可在 Dockerfile 中通过 --from=name 引用	docker buildx build --build-context project=./src .
--add-host	向构建容器的 /etc/hosts 添加自定义主机映射，支持 host-gateway 指向主机网关	docker buildx build --add-host myhost=8.8.8.8 --add-host host.docker.internal=host-gateway .
--progress	配置构建进度输出格式（支持 auto（默认，自动适配终端）、plain（纯文本）、tty（交互式彩色）、quiet（仅输出镜像 ID）、rawjson（JSON 流））	docker buildx build --progress plain .
--annotation	为镜像索引、清单或描述符添加 OCI 注解，支持按平台筛选	docker buildx build --annotation "manifest[linux/amd64]:foo=bar" -t myrepo/image --push .
--call	调用前端方法（如 check（验证配置不执行构建）、outline（查看构建参数）、targets（列出所有构建阶段））	验证配置：docker buildx build --call check .；列出阶段：docker buildx build --call targets .
--check	简写 --call=check，仅验证 Dockerfile 配置，不执行实际构建	docker buildx build --check .