docker-buildx

Docker Buildx — 构建引擎与多平台

为 docker build、buildx、多平台构建和构建优化提供专家指导。

使用时机

用户提及以下内容时，始终使用此技能：

• “docker build”、“buildx”、“构建镜像”
• “multi-platform”、“multi-arch”、“多平台构建”
• “linux/arm64”、“linux/amd64”
• “BuildKit”、“Build Cloud”
• “构建加速”、“build cache”、“构建缓存”
• “Docker build 慢”、“怎么加速 docker build”
• 需要为多种 CPU 架构构建镜像

核心命令

# Basic build
docker build -t myapp:v1 .

# Build with BuildKit (default in modern Docker)
DOCKER_BUILDKIT=1 docker build -t myapp:v1 .

# Build from specific Dockerfile
docker build -f Dockerfile.prod -t myapp:v1 .

# No cache rebuild
docker build --no-cache -t myapp:v1 .

Buildx — 多平台构建器

设置

# Create a builder instance
docker buildx create --name multiarch --use

# Inspect available platforms
docker buildx inspect --bootstrap

为多个平台构建

# Build and push directly (single command)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:v1.0.0 \
  --push .

# Build and load to local Docker (single platform only)
docker buildx build \
  --platform linux/arm64 \
  -t myapp:arm64 \
  --load .

# Build and export as tar
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:v1.0.0 \
  --output type=tar,dest=myapp.tar .

平台别名

别名	架构
linux/amd64	Intel/AMD 64 位
linux/arm64	ARM 64 位（Apple Silicon、AWS Graviton）
linux/arm/v7	ARM 32 位（Raspberry Pi 3）
linux/arm/v6	ARM 32 位（Raspberry Pi Zero）

BuildKit 功能

Secret 挂载

# Dockerfile
RUN --mount=type=secret,id=npmrc \
  cp /run/secrets/npmrc .npmrc && \
  npm ci && \
  rm .npmrc

docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

缓存挂载（在多次构建间保留）

# Python: persist pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install -r requirements.txt

# Node.js: persist npm cache
RUN --mount=type=cache,target=/root/.npm \
  npm ci

# Go: persist module cache
RUN --mount=type=cache,target=/root/.cache/go-build \
  go build -o server .

SSH 转发

# Clone private repo during build
RUN --mount=type=ssh \
  git clone [email protected]:org/private-repo.git

docker buildx build --ssh default -t myapp .

内联缓存（将缓存导出到镜像中）

# Export cache metadata into the image itself
docker buildx build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t myapp:latest \
  --push .

# Later builds can use this image as cache source
docker build --cache-from myapp:latest -t myapp:v2 .

分层缓存 — 构建前先拉取

# Pull previous image for layer cache
docker pull myapp:latest || true
docker build \
  --cache-from myapp:latest \
  -t myapp:${TAG} .

GitHub Actions — 多平台

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: user/app:latest
    cache-from: type=gha          # GitHub Actions cache
    cache-to: type=gha,mode=max

工作流 — 推荐构建流程

步骤 1：创建 Builder：docker buildx create --name multiarch --driver docker-container --use 步骤 2：选择方案：单平台（--load）还是多平台（--push）？交叉编译还是 QEMU？ 步骤 3：配置 Dockerfile：使用 --platform=$BUILDPLATFORM + ARG TARGETOS TARGETARCH 步骤 4：执行构建：docker buildx build --platform linux/amd64,linux/arm64 -t app --push . 步骤 5：验证：使用 docker buildx imagetools inspect app 确认多架构 manifest

注意事项 — 常见问题

• 多平台构建时使用 --load：--load 仅适用于单个平台。→ 解决方法：多平台构建时使用 --push 或 --output type=oci,dest=image.tar；或者使用 --load 构建单个平台。
• QEMU 仿真速度慢：在 AMD 上构建 ARM 镜像会慢 5–10 倍。→ 解决方法：在 CI 中使用原生 ARM 运行器（GitHub Actions 上的 ubuntu-24.04-arm）；或者使用 Docker Build Cloud 进行原生多架构构建。
• 默认启用 BuildKit：现代 Docker 默认使用 BuildKit。→ 解决方法：在 Docker 23+ 中，DOCKER_BUILDKIT=1 不会产生任何作用；如需明确控制 BuildKit，请使用 docker buildx build。
• 未先拉取就使用 --cache-from：Docker 不会自动拉取缓存镜像。→ 解决方法：在 docker build --cache-from myapp:latest 前运行 docker pull myapp:latest || true。

边界 — 能力边界（适用与不适用场景）

分类	场景	说明
✅ 能做	多平台构建（linux/amd64,arm64）	buildx + QEMU/交叉编译/原生节点
✅ 能做	BuildKit 高级特性	secret mount、cache mount、SSH 转发、内联缓存
✅ 能做	Docker Build Cloud 接入	云端构建 + 团队共享缓存
⚠️ 需条件	多平台 + --load	仅支持单平台，多平台需 --push
⚠️ 需条件	ARM 本地无 QEMU	需 docker run --privileged --rm tonistiigi/binfmt --install all
❌ 超范围	Dockerfile 编写	使用 docker-dockerfile
❌ 超范围	基础 docker build/tag/push	使用 docker-build
❌ 超范围	容器编排（Compose/Swarm）	使用 docker-compose/docker-production

不适用此技能的情况

❌ 跳过	✅ 改用
编写 Dockerfile 内容	docker-dockerfile
基于 Compose 的构建	docker-compose
Docker 基础知识	docker-basics
运行容器	docker-run

安全与稳定性

• 切勿在构建日志中暴露机密信息。请使用 BuildKit 的 --secret 或 CI 的机密信息屏蔽功能。
• 多平台镜像必须推送到镜像仓库 — --load 仅适用于单个平台。
• 在 CI 中拉取缓存镜像时应使用 || true — 首次构建时不会有缓存。

📚 官方文档参考

文档	地址
Docker Build	https://docs.docker.com/build/
Buildx 参考	https://docs.docker.com/reference/cli/docker/buildx/
BuildKit	https://docs.docker.com/build/buildkit/
Docker Build Cloud	https://docs.docker.com/build-cloud/
多平台构建	https://docs.docker.com/build/building/multi-platform/
构建缓存	https://docs.docker.com/build/cache/

🧭 Docker 技能之旅

📍 你在这里：docker-buildx — 构建引擎

← 上一步：docker-dockerfile — 编写 Dockerfile → 下一步：docker-run — 运行容器 / docker-cicd — CI/CD