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 架构构建镜像时，应使用此技能。

主要能力

核心构建命令

# 基础构建
docker build -t myapp:v1 .

# 使用 BuildKit（现代 Docker 默认）
DOCKER_BUILDKIT=1 docker build -t myapp:v1 .

# 从指定 Dockerfile 构建
docker build -f Dockerfile.prod -t myapp:v1 .

# 不使用缓存重建
docker build --no-cache -t myapp:v1 .

Buildx 多平台构建器

设置：

# 创建构建器实例
docker buildx create --name multiarch --use

# 查看可用平台
docker buildx inspect --bootstrap

为多个平台构建：

# 直接构建并推送（单条命令）
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:v1.0.0 \
  --push .

# 构建并加载到本地 Docker（仅单平台）
docker buildx build \
  --platform linux/arm64 \
  -t myapp:arm64 \
  --load .

# 构建并导出为 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 .

Cache 挂载（跨构建持久化）：

# Python：持久化 pip 缓存
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install -r requirements.txt

# Node.js：持久化 npm 缓存
RUN --mount=type=cache,target=/root/.npm \
  npm ci

# Go：持久化模块缓存
RUN --mount=type=cache,target=/root/.cache/go-build \
  go build -o server .

SSH 转发：

# 构建期间克隆私有仓库
RUN --mount=type=ssh \
  git clone git@github.com:org/private-repo.git

docker buildx build --ssh default -t myapp .

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

# 将缓存元数据导出到镜像本身
docker buildx build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t myapp:latest \
  --push .

# 后续构建可将该镜像作为缓存源
docker build --cache-from myapp:latest -t myapp:v2 .

层缓存——构建前先拉取：

# 拉取之前的镜像以使用层缓存
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-to: type=gha,mode=max

使用方式

推荐构建流程：

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

适用场景

多平台构建（linux/amd64、arm64）：buildx + QEMU/交叉编译/原生节点
BuildKit 高级特性：secret mount、cache mount、SSH 转发、内联缓存
Docker Build Cloud 接入：云端构建 + 团队共享缓存

限制与注意事项

常见陷阱：

--load 与多平台：--load 仅适用于单一平台。恢复方式：多平台使用 --push 或 --output type=oci,dest=image.tar；或构建单平台并使用 --load。
QEMU 模拟较慢：在 AMD 上构建 ARM 会慢 5-10 倍。恢复方式：在 CI 中使用原生 ARM runner（GitHub Actions 上的 ubuntu-24.04-arm）；或使用 Docker Build Cloud 的原生多架构构建器。
默认使用 BuildKit：现代 Docker 默认使用 BuildKit。恢复方式：在 Docker 23+ 上 DOCKER_BUILDKIT=1 是空操作；使用 docker buildx build 显式控制 BuildKit。
未先拉取就使用 --cache-from：Docker 不会自动拉取缓存镜像。恢复方式：在 docker build --cache-from myapp:latest 之前执行 docker pull myapp:latest || true。

能力边界：

需条件：多平台 + --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 密钥掩码。
多平台镜像必须推送到 registry——--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 Skills 旅程

当前位置：docker-buildx — 构建引擎

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