docker-buildx

Docker Buildx 多平台镜像构建

补充说明

docker buildx 基于 BuildKit 构建镜像，支持多平台、构建缓存和多种输出。它通过 builder 实例管理构建环境，默认的 docker driver 功能有限。

常用示例

docker buildx version
docker buildx create --name multi --driver docker-container --use
docker buildx inspect --bootstrap
docker buildx ls
docker buildx build -t app:latest .
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example.com/app:1.0 --push .
docker buildx build --platform linux/amd64 -t app:dev --load .
docker buildx build --cache-to type=registry,ref=registry.example.com/app:cache \
  --cache-from type=registry,ref=registry.example.com/app:cache \
  -t app:1.0 --push .
docker buildx imagetools inspect registry.example.com/app:1.0
docker buildx rm multi

易错点与排错

• 多平台构建不能 --load 到本地；要么 --push，要么输出到 OCI/目录。
• 默认 docker driver 不支持多平台和部分缓存特性；用 docker-container driver。
• 新建 builder 后要 inspect --bootstrap；镜像没拉下来时构建会卡住。
• 跨架构构建依赖 QEMU 或原生节点；模拟构建会明显变慢。
• registry 认证要在构建前完成；--push 失败先看 docker login。
• 缓存导入导出会增加构建时间；CI 里按命中率决定是否启用。
• --platform 和基础镜像的架构要匹配；否则运行时会报 exec format error。
• BuildKit 版本和 Docker 版本相关；升级后重新验证构建参数。

相关命令

• docker-compose — 本地编排
• buildctl — 直接调用 BuildKit
• crane / regctl — 镜像搬运与检查