Docker Buildx

Docker Buildx — 构建引擎与多平台

Expert guidance for docker build, buildx, multi-platform builds, and build optimization.

When to Use

ALWAYS use this skill when the user mentions:

• "docker build", "buildx", "构建镜像"
• "multi-platform", "multi-arch", "多平台构建"
• "linux/arm64", "linux/amd64"
• "BuildKit", "Build Cloud"
• "构建加速", "build cache", "构建缓存"
• "Docker build 慢", "怎么加速 docker build"
• Need to build images for multiple CPU architectures

Core Commands

# 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 — Multi-Platform Builder

Setup

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

# Inspect available platforms
docker buildx inspect --bootstrap

Build for Multiple Platforms

# 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 .

Platform Aliases

BuildKit Features

Secret Mount

# 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 .

Cache Mount (Persist Across Builds)

# 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 Forwarding

# Clone private repo during build
RUN --mount=type=ssh \
  git clone git@github.com:org/private-repo.git

docker buildx build --ssh default -t myapp .

Inline Cache (Export Cache into Image)

# 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 .

Layer Caching — Pull Before Build

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

GitHub Actions — Multi-Platform

- 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

Workflow — 推荐构建流程

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

Gotchas — Common Pitfalls

• `--load` with multi-platform: --load only works for a SINGLE platform. → Recovery: Use --push or --output type=oci,dest=image.tar for multi-platform; or build single platform with --load.
• QEMU emulation is slow: Building ARM on AMD is 5-10x slower. → Recovery: Use native ARM runners in CI (ubuntu-24.04-arm on GitHub Actions); or Docker Build Cloud for native multi-arch builders.
• BuildKit by default: Modern Docker uses BuildKit by default. → Recovery: DOCKER_BUILDKIT=1 is a no-op on Docker 23+; use docker buildx build for explicit BuildKit control.
• `--cache-from` without pulling first: Docker won't pull the cache image automatically. → Recovery: docker pull myapp:latest || true before docker build --cache-from myapp:latest.

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

When NOT to Use This Skill

Security & Stability

• Never expose secrets in build logs. Use --secret for BuildKit or CI secrets masking.
• Multi-platform images must be pushed to a registry — --load only works for single platform.
• Cache images in CI should be pulled with || true — first build won't have a cache.

📚 官方文档参考

🧭 Docker Skills Journey

📍 You are here: `docker-buildx` — 构建引擎

← Previous: docker-dockerfile — Write Dockerfiles → Next: docker-run — Run containers / docker-cicd — CI/CD

多平台构建：linux/amd64 + linux/arm64

# 创建 builder
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap

# 单命令多平台
docker buildx build --platform linux/amd64,linux/arm64 --tag myapp:latest --push .

FROM --platform=$BUILDPLATFORM golang:1.23-alpine AS builder
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -ldflags="-s -w" -o /app .
FROM alpine:3.20
COPY --from=builder /app /usr/local/bin/app
ENTRYPOINT ["app"]

# 验证 manifest
docker buildx imagetools inspect myapp:latest
# Name: docker.io/library/myapp:latest
# Manifests:
#   sha256:abc... (amd64)
#   sha256:def... (arm64)

# 仅构建到本地
docker buildx build --platform linux/amd64 --load -t myapp:local .

BuildKit 密钥挂载：避免泄露到镜像层

# syntax=docker/dockerfile:1
FROM node:22-alpine
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm install --registry=https://private-registry.com

# 文件挂载
docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .
# 环境变量
echo "$NPM_TOKEN" | docker buildx build --secret id=npmrc,src=/dev/stdin -t myapp .

常见场景

BuildKit 缓存挂载：加速重复构建

RUN --mount=type=cache,target=/cache/dir some-heavy-command

按生态

# Go
RUN --mount=type=cache,target=/go/pkg/mod go mod download
# Maven
RUN --mount=type=cache,target=/root/.m2 mvn dependency:go-offline -B
# npm
RUN --mount=type=cache,target=/root/.npm npm ci
# pip
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
# Rust
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    --mount=type=cache,target=/app/target \
    cargo build --release

# 清理缓存
docker buildx prune --filter=until=24h
docker buildx prune --all

BuildKit SSH 转发：安全访问私有仓库

# syntax=docker/dockerfile:1
FROM golang:1.23-alpine
RUN apk add --no-cache git openssh-client
ENV GOPRIVATE=github.com/mycompany/*
RUN --mount=type=ssh \
    mkdir -p ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts && go mod download

eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa
docker buildx build --ssh default -t myapp .

Node.js 私有包

FROM node:22-alpine
RUN --mount=type=ssh \
    git config --global url."git@github.com:".insteadOf "https://github.com/" && npm install

GitHub Actions 多平台构建

name: Build Multi-Arch
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: type=semver,pattern={{version}} | type=sha,format=short
      - uses: docker/build-push-action@v6
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Docker Buildx 架构

docker CLI (docker buildx build)
    ↓ gRPC
Buildx Client
    ↓
Builder Instance
    ├── Node 1 (amd64)
    ├── Node 2 (arm64)
    └── Node N (...)
    Driver: docker / docker-container / kubernetes / remote

docker buildx create --name mybuilder --driver docker-container
docker buildx ls
docker buildx use mybuilder
docker buildx inspect --bootstrap
docker buildx rm mybuilder

Buildx Driver 选型

决策树

需要多平台？→ 否 → docker（零配置）
需要多平台？→ 是 → 在 K8s 中？→ 是 → kubernetes
                              → 否 → docker-container + QEMU

docker buildx create --name multiarch --driver docker-container --use
docker buildx create --name k8s-builder --driver kubernetes --driver-opt replicas=3
docker buildx create --name remote --driver remote tcp://buildkitd:1234

多平台构建策略

QEMU（最简单）

docker run --privileged --rm tonistiigi/binfmt --install all
docker buildx build --platform linux/amd64,linux/arm64 -t app .

原生节点（推荐生产）

docker buildx create --name multiarch --driver docker-container
docker buildx create --name multiarch --append --node arm64-node ssh://arm-server

交叉编译（最快，有语言限制）

FROM --platform=$BUILDPLATFORM golang:1.23 AS builder
ARG TARGETOS TARGETARCH
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build

Docker Build Cloud

本地/CI → Build Cloud（云端 BuildKit 集群） → 推送到 Registry
              ↑
         共享缓存（团队复用）

接入

docker login
docker buildx create --name cloud-builder --driver cloud --use
docker buildx build --builder cloud-builder --platform linux/amd64,linux/arm64 --tag myorg/myapp:latest --push .

GitHub Actions

- uses: docker/setup-buildx-action@v3
  with:
    driver: cloud
    endpoint: myorg/cloud-builder
- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: myorg/myapp:latest