Apple Silicon 普及后在 Mac 上构建的镜像跑不了 Linux 服务器成了新痛点。本文详解 Docker buildx 的安装、配置、多平台构建全流程以及 CI/CD 中的最佳实践。一、为什么需要多平台构建1.1 问题的根源Docker 镜像是平台相关的。一个在 x86_64 机器上构建的镜像包含的是 x86_64 架构的二进制文件无法在 ARM64 机器如 Apple M1/M2、AWS Graviton上运行。# 在 x86 机器上构建 docker build -t myapp . # 推到 ARM 服务器上运行 → 报错 docker: Error response from daemon: image with reference myapp was found but does not match the specified platform: wanted linux/arm64, actual: linux/amd641.2 传统解法 vs buildx传统做法分别在 x86 和 ARM 机器上构建然后手动打不同 tag。# x86 机器 docker build -t myapp:amd64 . docker push myapp:amd64 # ARM 机器 docker build -t myapp:arm64 . docker push myapp:arm64buildx 做法一条命令同时构建多平台镜像自动合并为 manifest list。docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest --push .二、安装与启用 buildx2.1 检查是否已安装docker buildx version # 输出github.com/docker/buildx v0.12.0 ...Docker Desktop 和 Docker Engine 23.0 已内置 buildx。如果未安装# Linux mkdir -p ~/.docker/cli-plugins curl -SL https://github.com/docker/buildx/releases/download/v0.12.0/buildx-v0.12.0.linux-amd64 \ -o ~/.docker/cli-plugins/docker-buildx chmod x ~/.docker/cli-plugins/docker-buildx2.2 创建并启用 builder# 查看现有 builder docker buildx ls # 创建新的 builder支持多平台 docker buildx create --name multiarch --use # 启动 builder docker buildx inspect --bootstrap # 验证支持的平台 docker buildx inspect --bootstrap | grep Platforms # 输出linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6三、多平台构建实战3.1 基础多平台构建# Dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build EXPOSE 3000 CMD [node, dist/main.js]# 构建并推送到 Registry必须 --push 或 --load docker buildx build \ --platform linux/amd64,linux/arm64 \ -t myregistry.com/myapp:latest \ --push \ .关键参数--platform指定目标平台逗号分隔--push构建后直接推送到 Registry--load构建后加载到本地 Docker只能单平台-t镜像 tag3.2 本地测试多平台镜像# 构建 arm64 镜像并加载到本地用于测试 docker buildx build \ --platform linux/arm64 \ -t myapp:arm64-test \ --load \ . # 运行测试 docker run --rm myapp:arm64-test3.3 使用缓存加速# 本地缓存 docker buildx build \ --platform linux/amd64,linux/arm64 \ -t myapp:latest \ --cache-from typelocal,src/tmp/buildx-cache \ --cache-to typelocal,dest/tmp/buildx-cache \ --push \ . # Registry 缓存推荐 CI/CD docker buildx build \ --platform linux/amd64,linux/arm64 \ -t myapp:latest \ --cache-from typeregistry,refmyregistry.com/myapp:cache \ --cache-to typeregistry,refmyregistry.com/myapp:cache,modemax \ --push \ .四、Dockerfile 多平台适配4.1 基础镜像选择# 使用官方多平台基础镜像 FROM node:18-alpine # 支持 amd64 arm64 # 避免使用单平台镜像 FROM some-image:latest # 可能只有 amd644.2 平台特定依赖# 根据平台安装不同依赖 FROM golang:1.21-alpine # 安装平台特定的包 RUN apk add --no-cache \ ${TARGETPLATFORM:musl-dev} \ gcc # 使用 TARGETARCH 变量 ARG TARGETARCH RUN echo Building for ${TARGETARCH}4.3 交叉编译 Go 应用FROM golang:1.21-alpine AS builder ARG TARGETOS ARG TARGETARCH WORKDIR /app COPY . . # 交叉编译 RUN CGO_ENABLED0 GOOS${TARGETOS} GOARCH${TARGETARCH} \ go build -o /app/server . FROM alpine:3.18 COPY --frombuilder /app/server /usr/local/bin/ CMD [server]# 一条命令构建多平台 docker buildx build \ --platform linux/amd64,linux/arm64 \ -t myapp:latest \ --push \ .4.4 交叉编译 Rust 应用FROM rust:1.70-alpine AS builder ARG TARGETARCH RUN apk add --no-cache musl-dev WORKDIR /app COPY . . # 根据架构设置目标 RUN if [ $TARGETARCH arm64 ]; then \ rustup target add aarch64-unknown-linux-musl \ cargo build --release --target aarch64-unknown-linux-musl; \ else \ cargo build --release; \ fi FROM alpine:3.18 ARG TARGETARCH COPY --frombuilder /app/target/${TARGETARCH:aarch64-unknown-linux-musl/}release/myapp /usr/local/bin/ CMD [myapp]五、CI/CD 中的多平台构建5.1 GitHub Actionsname: Build Multi-Arch Image on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Set up QEMU uses: docker/setup-qemu-actionv3 - name: Set up Docker Buildx uses: docker/setup-buildx-actionv3 - name: Login to Registry uses: docker/login-actionv3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Build and Push uses: docker/build-push-actionv5 with: context: . push: true platforms: linux/amd64,linux/arm64 tags: ghcr.io/${{ github.repository }}:latest cache-from: typegha cache-to: typegha,modemax5.2 GitLab CIbuild-multiarch: stage: build image: docker:24-dind services: - docker:24-dind script: - docker buildx create --use - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker buildx build --platform linux/amd64,linux/arm64 -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --push .5.3 Jenkins Pipelinepipeline { agent any stages { stage(Build Multi-Arch) { steps { script { docker.withRegistry(https://registry.example.com, credentials-id) { sh docker buildx create --use docker buildx build \ --platform linux/amd64,linux/arm64 \ -t registry.example.com/myapp:${BUILD_NUMBER} \ --push \ . } } } } } }六、常见问题与解法6.1 构建报错no match for platform现象ERROR: Multiple platforms feature is currently not supported for docker driver.原因使用了默认的 docker driver不支持多平台。解法# 创建使用 docker-container driver 的 builder docker buildx create --name multiarch --driver docker-container --use docker buildx inspect --bootstrap6.2 构建速度慢原因QEMU 模拟 ARM 指令速度比原生慢 5-10 倍。解法使用交叉编译代替 QEMU 模拟Go/Rust/C 等编译型语言启用缓存见 3.3 节使用 GitHub Actions 的 setup-qemu-action setup-buildx-action6.3 本地无法运行多平台镜像现象docker buildx build --platform linux/amd64,linux/arm64 -t myapp . docker run myapp # 报错原因--load 只能加载单平台镜像。解法# 方案一指定单平台加载 docker buildx build --platform linux/amd64 -t myapp --load . # 方案二构建后直接推送不在本地运行 docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .6.4 基础镜像不支持多平台现象某个基础镜像只有 amd64 版本。解法寻找官方多平台替代镜像自己构建多平台基础镜像使用 TARGETPLATFORM 条件安装不同依赖七、最佳实践清单基础镜像选官方多平台版本如 node:18-alpine、golang:1.21编译型语言用交叉编译避免 QEMU 模拟CI/CD 中启用缓存加速重复构建测试时加载单平台镜像推送时用多平台使用 --cache-to typeregistry在团队间共享缓存定期清理 builder 缓存docker buildx prune八、总结场景命令本地单平台测试docker buildx build --platform linux/arm64 --load .推送多平台镜像docker buildx build --platform linux/amd64,linux/arm64 --push .CI/CD 构建GitHub Actions docker/build-push-action加速构建--cache-from typeregistry 交叉编译Docker buildx 让多平台构建从分别在多台机器上构建变成一条命令搞定。掌握它就能轻松应对 Apple Silicon、AWS Graviton、阿里云倚天等多架构环境。