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
| Alias | Architectures |
|-------|---------------|
| linux/amd64 | Intel/AMD 64-bit |
| linux/arm64 | ARM 64-bit (Apple Silicon, AWS Graviton) |
| linux/arm/v7 | ARM 32-bit (Raspberry Pi 3) |
| linux/arm/v6 | ARM 32-bit (Raspberry Pi Zero) |
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 [email protected]: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 — 能力边界（适用与不适用场景）
| 分类 | 场景 | 说明 |
|------|------|------|
| ✅ 能做 | 多平台构建（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 |
When NOT to Use This Skill
| ❌ Skip | ✅ Use Instead |
|---------|---------------|
| Writing Dockerfile content | docker-dockerfile |
| Compose-based builds | docker-compose |
| Docker basics | docker-basics |
| Running containers | docker-run |
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 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 Skills Journey
📍 You are here: docker-buildx — 构建引擎
← Previous: docker-dockerfile — Write Dockerfiles
→ Next: docker-run — Run containers / docker-cicd — CI/CD