多架构镜像构建实战：Docker Buildx与Manifest List原理及CI落地

1. 为什么多架构镜像成为刚需

我开始做多架构镜像这件事，起因很实际：公司的生产环境里既有 x86 的 Intel/AMD 服务器，后来又上了一批 ARM 的鲲鹏、飞腾机器，团队里还有一堆用 Apple Silicon 笔记本的同事，客户那边偶尔还要部署到树莓派上。一开始我图省事，各个架构单独打镜像，tag 后面再挂个 -amd64、-arm64 的后缀，结果维护起来非常痛苦。做一个版本要构建三四个镜像，Dockerfile 里还得写一堆平台分支判断，发布脚本越来越长，偶尔还出现忘记推送某个架构镜像导致线上拉取失败的尴尬。

后来我把这套流程整体切换到 Docker Buildx 多架构构建方案，一份 Dockerfile 跑一次构建，就能同时产出 amd64、arm64 等多个平台的镜像，并且通过 Manifest List（镜像索引）合并成一个 tag 推到仓库里。用户在任意架构的机器上执行 docker pull，Docker 会自动拉取对应架构的镜像层，完全不需要手动区分。这套方案解决的核心问题就是：用最低的维护成本，让同一个镜像在任何 CPU 架构上都能开箱即用。

这篇文章我会把这套方案的完整落地过程写出来，包括原理、环境准备、具体命令、Dockerfile 写法、CI 集成、缓存加速，最后附上我实际踩过的坑和排查思路。适合正在做多架构交付、或者刚开始接触 Buildx 的开发和运维同学参考。

1.1 当前主流 CPU 架构的分布情况

在规划多架构方案之前，先得清楚我们要覆盖哪些架构。目前最常见的几个目标平台是：

• linux/amd64：绝大多数 x86 服务器、云主机、传统 PC 服务器，装机量最大，是默认的第一平台。
• linux/arm64：ARM 架构的 64 位服务器，比如华为鲲鹏、AWS Graviton、Ampere Altra，以及苹果 M 系列芯片的 Linux 虚拟机。云厂商近年来大量提供这类实例，性价比优势明显。
• linux/arm/v7：树莓派 2/3、大量 ARM 开发板、部分 NAS 设备，虽然性能弱但存量很大，很多边缘计算场景还在用它。
• linux/arm/v6：树莓派 1 代、Zero 等更老的设备，相对小众，视业务情况决定是否需要。
• linux/ppc64le、linux/s390x、linux/riscv64：Power 服务器、IBM Z、RISC-V 等小众架构，一般只有特定行业才会用到，通常是在基础设施类镜像中才会覆盖。

做方案时我建议分两步走：第一优先级永远先覆盖 linux/amd64 和 linux/arm64，这两者覆盖了 90% 以上的需求；如果业务确实涉及边缘设备，再把 arm/v7 加进来。架构覆盖越多，构建时间越长，QEMU 模拟的性能瓶颈越明显，所以不要一上来就贪全。对我们团队的实际运维状况而言，容器化已经是标准交付方式了，镜像如果只能跑在 x86 上，后续无论是要迁移到 ARM 云主机，还是支持本地 Mac 开发调试，都会非常被动。

1.2 Manifest List 与镜像索引的原理

很多人第一次看到多架构镜像时会有疑问：Docker 是怎么做到一个 tag 对应多个架构的？背后的关键就是 Manifest List，在 OCI 规范里叫 Image Index。

普通单架构镜像的结构是：仓库 tag 指向一个 Manifest，Manifest 里描述了一层层的镜像层和配置信息。而多架构镜像的结构是多了一层索引：tag 指向的不是某个具体的 Manifest，而是一个 Manifest List，列表里记录了每个平台架构对应的 Manifest 引用及其摘要（digest）。当你在某台机器上执行 docker pull 时，Docker 客户端会把自己当前运行时的 os/arch（比如 linux/arm64）发到仓库服务端，服务端从 Manifest List 里找到匹配项，返回对应的 Manifest，然后客户端再按这个 Manifest 去拉取镜像层。

理解这个机制后，很多问题就迎刃而解了：

• 为什么我在 x86 机器上拉多架构镜像，实际下载的层还是 amd64 的？因为客户端自动选择了对应平台的层，其它架构的层不会被下载。
• 为什么有些比较老的镜像仓库工具显示的信息不完整？因为有些工具不支持 OCI Image Index 这种新格式，需要升级或开启实验特性。
• 为什么不能用 docker tag 简单地把两个架构的镜像合并？因为 Manifest List 必须由 Buildx 或 docker manifest 命令创建，普通 tag 操作不涉及这个层面的元数据。

另外要注意，Manifest List 不是把两个镜像简单打包在一起，而是对每个架构单独构建镜像，然后把它们的引用和平台信息记录到索引里。所以多架构构建的本质是先构建多个架构的真实镜像，最后再合并索引。

1.3 三种常见多架构构建方案的取舍

我调研和实际试过的方案大体有三种，各有适用场景：

方案一：使用 Buildx + QEMU 用户态模拟构建。 这是目前最主流、维护成本最低的方式。在构建机上注册 QEMU 的 binfmt 处理器，让 BuildKit 在需要执行 arm64 程序时自动通过模拟器运行。好处是只需要一台机器就能构建所有平台镜像，缺点是 arm64 等非本机架构的构建速度明显偏慢，尤其是编译型语言和安装大量软件包时。

方案二：多台原生架构构建机组成构建矩阵。 比如我在公司内部就见过有的团队准备了两套环境，x86 机器上构建 amd64 镜像，ARM 机器上构建 arm64 镜像，最后再把索引合并。优点是每台机器都是原生速度，构建效率高，缺点是要维护多套构建环境，CI 流水线的复杂度会上升，也因此比较适合对构建速度敏感、且基础设施本身就有多架构机器可用的团队。

方案三：在构建脚本里做交叉编译。 比如 Go 语言可以通过设置 GOARCH 和 CGO_ENABLED=0 直接在一个平台上产出其他架构的二进制，然后打进镜像。这个方案构建速度最快，但对语言和编译工具链有严格要求。C/C++ 依赖比较多、或者需要依赖系统原生库的场景就不太适用，Node.js 里带原生模块的场景也会比较麻烦。

从通用性和可维护性角度，我最终选了方案一作为主流程，方案三作为某些特定语言的性能优化手段。这也是绝大多数开源项目在推出的多架构镜像时实际采用的方式，社区验证充分，遇到问题也容易找到参考案例。

2. 环境准备与工具链选型

这套方案对环境的要求其实不高，但有几个前置条件必须提前确认好，否则后面构建时会出现各种莫名其妙的错误。我按自己踩坑的顺序来梳理。

2.1 版本要求与 Buildx 插件启用

首先确认 Docker 版本。Buildx 作为 Docker CLI 的插件功能完整可用，一般要求 Docker 20.10 以上，新版本基本开箱即用。如果你本机装的是 Docker Desktop，新版本里已经默认集成 Buildx 了。Linux 环境如果是手动安装的较新版本 Docker Engine，通常也自带 buildx 插件；但有些用系统包管理器安装的旧版本可能没有，这时需要手动安装。

判断是否可用，直接执行：

bash复制docker buildx version

如果输出类似 github.com/docker/buildx v0.xx.x 的信息，说明插件已经可用。如果提示 docker: 'buildx' is not a docker command，就需要在 Docker 官方发布页下载对应版本的 buildx 插件二进制，放到 ~/.docker/cli-plugins/ 目录，并赋予执行权限：

bash复制mkdir -p ~/.docker/cli-plugins
chmod +x docker-buildx
cp docker-buildx ~/.docker/cli-plugins/docker-buildx

另外需要确认 BuildKit 是否正常。Buildx 的底层是构建引擎 BuildKit，正常情况下由 Buildx 自动管理，但如果你直接在 DOCKER_BUILDKIT=1 环境下使用老的 docker build，这只是用了 BuildKit 的默认构建器，并不具备多平台构建能力。多架构构建必须走 Buildx 创建的 docker-container 驱动构建实例，这一点务必记住。

2.2 QEMU 与 binfmt_misc 的关键作用

现在解释一下为什么 x86 机器能构建 arm64 镜像：这依赖 Linux 内核的 binfmt_misc 机制和 QEMU 的用户态模拟。

binfmt_misc 是内核提供的一个机制，它允许为不是本机原生格式的可执行文件指定一个解释器。当你在 x86 机器上尝试执行一个 arm64 的 ELF 文件时，内核发现这个文件的 magic number 没有匹配到原生格式，就去查 binfmt_misc 的注册表，找到对应架构的解释器后交给它执行。这个解释器就是 QEMU 的用户态模拟程序，比如 qemu-aarch64-static、qemu-arm-static。

在 Docker 环境下，最省事的做法是运行一个官方社区维护的 binfmt 镜像来完成注册工作：

bash复制docker run --privileged --rm tonistiigi/binfmt --install all

执行完后可以验证一下：

bash复制ls /proc/sys/fs/binfmt_misc/
docker run --rm --platform linux/arm64 docker.io/arm64v8/alpine uname -m

如果最后一条命令在 x86 机器上输出了 aarch64，说明 QEMU 模拟链路已经打通。注意，--platform 指定的是容器运行时要模拟的平台，binfmt 注册必须在构建机的宿主内核层面生效，所以如果是自己搭的构建机，这个步骤要放到构建前的初始化脚本里；如果用的是 Docker Desktop，桌面版已经内置了跨平台运行支持，不需要额外操作。

2.3 构建驱动选择：为什么必须用 docker-container

Buildx 支持多种构建驱动，包括 docker、docker-container、kubernetes 等。默认的 docker 驱动兼容性最强，但它有几个限制：一是它能用的原生 BuildKit 能力有限，二是它本质上还是复用宿主机的 Docker daemon，无法同时处理多平台构建的模拟执行环境。所以做多架构构建时，必须要创建一个 docker-container 驱动的构建实例。

docker-container 驱动会独立启动一个 BuildKit 容器作为构建环境，在这个容器内部可以配置跨平台模拟，并且支持更高级的缓存导出、多节点并行构建等能力。这也是 Buildx 最核心的使用姿势。如果你发现某个构建失败的原因是和驱动有关，先检查 docker buildx ls 看看当前使用的实例是不是 docker-container。

创建实例的命令很简单：

bash复制docker buildx create --name multiarch --driver docker-container --platform linux/amd64,linux/arm64,linux/arm/v7
docker buildx use multiarch
docker buildx inspect --bootstrap

等 inspect 输出 Status: running 就说明实例已经启动。这里我补充一个细节：--platform 参数这里填的是你希望这个构建实例支持哪些平台，真正构建时 docker buildx build 命令里的 --platform 才是最终决定本次产出哪些平台的参数，两者要配合使用。

3. 核心实操：构建并推送多架构镜像

环境准备好之后，最核心的部分就是把项目构建成多架构镜像。这一节我用一个实际案例来演示，从 Dockerfile 到构建命令全流程走一遍。案例可以是一个简单的 Go HTTP 服务，也可以用任意语言替换，重点是理解平台差异的处理方式。

3.1 Dockerfile 编写要点与平台差异处理

Dockerfile 要想适配多架构，第一个要理解的是 BuildKit 提供的内置 ARG：TARGETPLATFORM、TARGETOS、TARGETARCH、TARGETVARIANT，以及对应的 BUILDPLATFORM、BUILDOS、BUILDARCH。这些变量在构建过程中会自动注入，不需要手动定义，但在 FROM 阶段如果想要使用它们，需要在对应的构建阶段前先声明：

dockerfile复制FROM --platform=$BUILDPLATFORM golang:1.22-alpine AS builder
ARG TARGETOS
ARG TARGETARCH
RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /app/server .

这里有两个关键点：

• FROM --platform=$BUILDPLATFORM 的意思是，构建阶段使用的镜像跟随当前构建机的平台，这样拉取 golang 编译镜像时不用走 QEMU 模拟，构建速度会快很多。编译工具链本身是跨平台可执行文件，Go 在编译阶段只要设置了正确的 GOOS/GOARCH 就能产出目标平台的二进制，所以这是最优解。
• 第二步把 TARGETOS 和 TARGETARCH 传入编译参数，让编译产物对应到最终目标平台。Go 的这个流程非常顺畅，所以 Go 项目做多架构镜像是最省心的。

如果你的业务不是 Go，而是 Java，那更简单，因为 JVM 是纯字节码，同一个 jar 包可以在任何平台上运行，基础镜像选择 eclipse-temurin 这样的多架构镜像即可，无需在 Dockerfile 里做额外处理。Python 项目也类似，尽量选官方或维护良好的多架构基础镜像，不要自己从精简基础镜像开始堆依赖，否则很容易踩到平台相关的坑。

如果是 Node.js 且涉及 node-gyp、sharp、bcrypt 这类原生模块，情况会复杂一些。一般做法是确保在构建阶段安装模块时使用目标平台的镜像环境，并且尽量锁版本、启用镜像自带的预编译二进制下载。遇到原生模块装不上时，很多情况下是因为构建阶段被 QEMU 模拟导致安装脚本执行失败，这种场景建议把涉及到原生模块的步骤放到最终运行阶段，或者在官方构建镜像里直接完成安装。

多阶段构建是一个强烈推荐的模式：在编译阶段产出产物，运行阶段只放最小必要环境。这不仅能大幅缩小镜像体积，还能显著减少跨平台模拟带来的构建时间开销。

3.2 构建命令与参数详解

Dockerfile 就绪后，执行构建并通过 --push 直接推送：

bash复制docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t yourname/hello-server:1.0.0 \
  -t yourname/hello-server:latest \
  --push .

先解释参数含义：

• --platform 指定本次构建的目标平台列表，用逗号分隔。
• -t 可以写多个，构建完成后会为镜像创建多个 tag，但注意它们都会指向同一个 Manifest List。
• --push 构建完成后直接推送到镜像仓库，同时生成 Manifest List。这里有个细节：如果只写 --push 而没有 --load（或反过来），含义是不同的。--load 是把镜像加载到当前 Docker daemon 中，只适用于单平台场景；多平台场景下必须使用 --push，因为 Docker daemon 只能保存当前平台的镜像，无法保存多平台 Manifest List。
• 如果只是想在本地验证构建过程，可以在 --platform 只填当前本机的平台并配合 --load，但不建议做多平台验证明这样做。

构建完成后，用 imagetools inspect 来查看 Manifest List 内容和每个平台的 digest：

bash复制docker buildx imagetools inspect yourname/hello-server:1.0.0

输出会列出平台和 digest 的对应关系：

code复制Name:      docker.io/yourname/hello-server:1.0.0
MediaType: application/vnd.oci.image.index.v1+json
Platforms:
  linux/amd64, linux/arm64, linux/arm/v7

最后在实际机器上验证拉取：

bash复制docker pull yourname/hello-server:1.0.0
docker run --rm yourname/hello-server:1.0.0

x86 机器上拉取的就是 amd64 镜像，ARM 机器上拉取的就是 arm64 镜像，完全不需要指定架构。在 Windows/Mac 的 Docker Desktop 里还可以用 --platform 强制跑特定架构验证，这在本地调试时非常有用。

3.3 构建过程的流水线呈现与结果观察

实际执行时，你会看到 Buildx 先为每一个平台分别解析构建图，然后并行执行。第一次构建因为没有缓存，速度会比较慢；有缓存之后，每个平台之间相同的层会被复用，速度会快很多。这里有个经验：模拟构建时，尤其 arm64 平台会明显比 amd64 慢，通常在 2 到 5 倍之间，视具体构建任务的 CPU 强度和网络情况而定。如果你项目的构建任务很大，强烈建议参考第 4 节的缓存策略。

最终镜像仓库里除了能看到 1.0.0 标签，还可以在仓库页面看到它被标识为 Manifest List。有些仓库管理界面会对这种多架构镜像打上特殊的 mark，方便你在 UI 上判断。

4. 进阶：CI/CD 集成与加速优化

手动构建跑通只是第一步，真正落地到日常开发流程里必须接入 CI/CD。我以 GitLab CI 为例，讲一下我实际使用并验证过的配置思路，Jenkins 等其它流水线工具也是同样的思路，大同小异。

4.1 GitLab CI 实战配置

要在 GitLab Runner 上构建多架构镜像，有几个前提条件：Runner 所在机器需要支持 docker 执行器、能运行特权容器，这样才能在流水线里完成 QEMU binfmt 注册。参考的 .gitlab-ci.yml 核心片段：

yaml复制build-multiarch:
  stage: build
  image: docker:24
  services:
    - name: docker:24-dind
      command: ["--privileged"]
  before_script:
    - docker run --privileged --rm tonistiigi/binfmt --install arm64,arm
    - docker buildx create --name multiarch --driver docker-container --use
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  script:
    - docker buildx build --platform linux/amd64,linux/arm64 --push -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG .
  only:
    - tags

需要注意的三个细节：

• dind 容器要加 --privileged，否则在容器里运行 binfmt 注册不会生效，构建 arm64 平台时会出现 exec format error。
• 如果 Runner 有多台机器同时跑流水线，每台机器都要执行 binfmt 注册和 buildx 实例创建，所以这些步骤要放在每次构建的 before_script 里，而不是只在宿主机初始化时做一次。
• Docker-in-Docker 环境下缓存默认不持久，这也是为什么第 4.2 节里要把缓存推到独立的缓存仓库或使用 registry 类型缓存。

4.2 构建缓存与加速策略

多架构构建最大的痛点就是慢，尤其是走 QEMU 模拟时。加速的核心思路是尽量利用缓存，减少重复执行。

Buildx 支持 --cache-from 和 --cache-to 两个参数，通过导出来配置缓存策略。最常用的两种类型：

bash复制# 把缓存推到镜像仓库（推荐，适用于所有 CI）
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --cache-from=type=registry,ref=yourname/hello-server:buildcache \
  --cache-to=type=registry,ref=yourname/hello-server:buildcache,mode=max \
  --push -t yourname/hello-server:1.0.0 .

# GitHub Actions 中可以用 gha 类型，把缓存存在 Actions 缓存服务里

mode=max 表示保存所有层的缓存，包括中间构建阶段的层，适合多阶段构建且后续阶段容易被修改的项目；如果不加这个参数，默认只缓存最终镜像层，对多阶段构建的加速效果有限。

除了 Buildx 级别的缓存，Dockerfile 内部的层设计也会显著影响构建速度。我实际测试下来有几个经验：

• 尽量把不经常变化的指令放在 Dockerfile 的前面，比如 RUN apt-get update && apt-get install ... 这类基础依赖安装，可以先 COPY 依赖清单文件再执行安装，让依赖层尽量命中缓存。
• 加了 QEMU 模拟的构建阶段，如果某个 RUN 步骤非常耗时，考虑把它挪到不需要模拟的阶段，或者用 BUILDPLATFORM 阶段的交叉编译替代。
• 构建阶段的最终镜像不要装开发和构建工具，用多阶段构建把运行镜像缩小，这样 --push 时网络传输的数据量小很多。

对于大型项目，我个人的建议是把编译阶段的镜像固定版本，并锁住依赖版本，不要每次都跑 update，这在多架构模拟环境下能省下大量时间和网络流量。

4.3 OpenStack 与 QEMU 多架构虚拟机的联动场景

有些企业会在 OpenStack 环境中实际使用多架构虚拟机来跑业务，进而产生构建多架构镜像的需求。OpenStack 本身支持通过 flavor 和 image 机制创建不同 CPU 架构的虚拟机，比如在 x86 控制节点上使用 QEMU 的系统模拟能力创建 arm64 虚拟机实例。

这种场景下，一个很自然的做法是：用 OpenStack 创建的 ARM 虚拟机作为原生构建机，加入到 Buildx 的多节点构建集群中，让 amd64 镜像由 x86 构建机产出，arm64 镜像由 ARM 虚拟机产出，最后由任一节点合并 Manifest List 并推送。Buildx 是支持多节点构建的，创建构建实例时可以指定连接多个节点：

bash复制docker buildx create --name multiarch \
  --node amd64-builder --platform linux/amd64 \
  --driver docker-container ssh://build@x86-host

docker buildx create --name multiarch \
  --append \
  --node arm64-builder --platform linux/arm64 \
  --driver docker-container ssh://build@arm-host

docker buildx use multiarch

这样做的好处是各平台都是原生速度，构建效率非常高；缺点是需要维护多台构建机，并且 OpenStack 的虚拟机资源本身有额外开销。如果你的团队已经有现成的多架构 VM 资源，这种方案非常值得尝试。需要注意的是，OpenStack 环境里创建 ARM 虚拟机时，镜像需要提前准备好的 arm64 系统镜像，QEMU 模拟的执行效率通常远低于原生硬件，所以如果追求速度，尽量用原生架构的裸金属或虚拟机。

4.4 本地多架构调试技巧

除了 CI 流水线，本地开发时也经常需要验证多架构镜像。我常用的几个做法：

• 在 Docker Desktop 里直接用 docker run --platform linux/arm64 跑一个 arm64 容器做基础验证，Desktop 内置了 QEMU，不需要额外安装。
• 用 docker buildx build --platform linux/arm64 --load 在本地构建当前平台的 arm64 镜像并加载到本地 daemon（注意这里只能加载当前平台，所以适合单平台调试，不适合验证整个 Manifest List）。
• 构建完镜像后，用 docker buildx imagetools create --tag 把已经存在的不同平台镜像手动合并成多架构索引，这在某些 CI 场景下很实用。

5. 常见问题与排查实录

这部分我按实际踩过的坑做一个速查。多架构构建涉及环境、内核、网络、仓库等多层因素，问题往往不只有一个表象。我自己在排障时基本遵循这个顺序：先确认环境层，再看构建层，最后查网络和仓库层。

5.1 docker buildx 命令不存在

现象：执行 docker buildx version 时报 docker: 'buildx' is not a docker command。

原因：Docker 版本过老，或者 CLI 插件目录没有正确安装 buildx。

排查步骤：

bash复制docker version
ls ~/.docker/cli-plugins/

如果版本低于 20.10，先升级 Docker；如果版本较新但插件目录为空，手动下载 buildx 二进制放到 ~/.docker/cli-plugins/ 并加执行权限。安装完记得重启 Docker daemon 或重新打开终端。

5.2 QEMU 未注册导致 exec format error

现象：构建 arm64 平台时，报错类似 failed to solve: process "/bin/sh -c ..." did not complete successfully: exit code: 1，更细化的错误是 exec format error，或者 standard_init_linux.go:... exec user process caused: exec format error。

原因：binfmt_misc 没有注册对应的 QEMU 解释器，或者注册了但当前 Docker 环境没有正确使用它。

排查步骤：先在构建机上执行：

bash复制docker run --rm --privileged tonistiigi/binfmt --install all
docker run --rm --platform linux/arm64 docker.io/arm64v8/alpine uname -m

如果能输出 aarch64 就没问题。如果还是报 exec format error，检查是不是在非特权容器里跑的 binfmt 注册，或者构建实例是旧的（重新执行 docker buildx create --name multiarch --driver docker-container --use 后再试）。

另外，如果你是在 Windows 的 Docker Desktop 上构建，Desktop 自带 binfmt 支持，一般不会有这个问题；反而是在 Linux 裸机、云主机、CI Runner 上最容易忽略这一步。

5.3 Docker Desktop 启动失败或虚拟化未开启

现象：Windows 上安装 Docker Desktop 后启动报错，比如提示 Virtualization support not detected，或者 Docker Desktop failed to start，甚至 failed to connect to the docker api at npipe:////./pipe/dockerDesktopLinuxEngine。

原因：Docker Desktop 在 Windows 上依赖 WSL2 或 Hyper-V，而这些底层功能需要 CPU 虚拟化开启并正确配置。

排查步骤：

1. 进 BIOS/UEFI 确认 Intel VT-x 或 AMD-V 已开启。
2. 在 Windows 功能里确认“虚拟机平台”和“适用于 Linux 的 Windows 子系统”已启用。
3. 执行 wsl --status 确认 WSL 内核版本正常。
4. 如果 D 盘或系统盘空间不足，也容易导致启动失败，清理空间后重启。

npipe 连接失败的错误，通常是 Docker Engine 还没起来或者服务异常，优先看 Windows 服务列表里 Docker Desktop Service 的状态，以及事件查看器里的相关内容。这类问题基本都是宿主环境问题，而不是多架构构建本身的问题，但在团队协作时，新成员的机器如果卡在这一步，整个多架构流水线也无法正常参与本地调试。

5.4 镜像下载慢与推送失败

现象：docker pull 基础镜像非常慢，或者在 CI 里推送大镜像时超时。

原因：网络链路、远端仓库速率、以及镜像仓库侧对 Manifest List 的支持情况。

处理方案：

• 给本机 Docker daemon 配置 registry-mirrors 加速地址。在 /etc/docker/daemon.json 里加入：

json复制{
  "registry-mirrors": ["https://your-mirror-address"]
}

然后 systemctl restart docker。不同环境适用的加速地址不同，建议先用能稳定访问的地址，配置后跑一下 docker pull 测速。如果你用的不是 Docker Hub，而是云厂商的镜像仓库服务，也可以通过配置仓库凭证或私有化部署来降低网络延迟。

• 推送失败时，先看仓库是否支持 OCI Index 格式。部分老旧的私有仓库不支持 Manifest List，推送多架构镜像会失败，这时需要升级仓库服务，或者改用支持 OCI 的镜像仓库产品。
• 镜像体积过大也会导致推送超时，这是多阶段构建和层压缩能解决的问题。构建前先确认基础镜像是不是最小化，有没有把构建工具带进最终镜像。

5.5 ARM 平台构建缓慢或卡死

现象：构建耗时极长，甚至某个 RUN 步骤看起来卡住不动。

原因：QEMU 模拟执行用户态程序的效率远低于原生，编译类任务（比如 go build、apt-get 安装大量软件包、npm install 大量依赖）在模拟环境下耗时放大明显。

处理方案：

• 优先用交叉编译替代模拟执行（Go、Rust 场景通常可行）。
• 构建阶段用 --platform=$BUILDPLATFORM，不让模拟环境参与编译工具的拉取和安装。
• 开启缓存并把缓存推到 registry，让 CI 的增量构建不重复跑相同步骤。
• 如果实在无法避免模拟，考虑把该平台的原生构建机加入 Buildx 多节点集群。

6. 写在最后：几点实操心得

这套方案从调研到落地，我修正了自己最初的几个认知误区，这里分享几个关键体会。

第一，多架构构建不是简单的“换一条命令”。它牵涉到 Dockerfile 的平台差异处理、构建实例的驱动选择、QEMU 的注册、仓库对 Manifest List 的支持程度，以及 CI 环境的权限配置。每一层都可能有问题，所以建议先在本地把完整流程走通，再往 CI 迁移，不要两头并行调试。我吃过一次亏：本地构建没问题，推到 CI 就报 exec format error，最后排查到是 Runner 的 dind 没有加特权模式，白白折腾了一下午。

第二，编译型语言和解释型语言在多架构构建上的策略完全不同。Go、Rust 这类可以交叉编译的语言，尽量用 BUILDPLATFORM 加目标参数的方式，速度快且稳定；Java、Python 这类解释型或字节码类语言，重点是用好多架构基础镜像，核对依赖版本；Node.js 这类涉及原生模块的语言，需要留意模块的预编译二进制是否能覆盖目标平台，必要时在目标平台的模拟环境中安装模块。

第三，慢不可怕，没缓存才可怕。如果你觉得多架构构建太慢，先不要急着加机器，优先检查缓存的命中率。把依赖安装层和源码编译层拆开，把 --cache-to 和 --cache-from 配置到位，很多项目就能从每次构建十几分钟降到几分钟。我目前维护的项目，一次完整的多架构构建在 CI 里耗时约三四分钟，其中大部分时间花在模拟执行 arm64 的依赖安装上，增量构建时基本是秒级。

补充一个很实用的小技巧：如果团队里某台机器经常拉取慢，可以在本地把基础镜像提前 docker pull 下来，构建时 Buildx 会优先使用本地已经存在的镜像层，能省不少时间。另外，确保所有人使用一致的 Docker 版本和 Buildx 版本，团队协作时这种“环境漂移”引发的问题往往比镜像本身的问题还多。

多架构构建本身不是一个新技巧，但把它变成团队的标准发布流程，需要不少环境适配和自动化工作。这篇文章把我的完整实践路径写出来了，如果你在落地过程中遇到文中没覆盖到的问题，欢迎结合实际报错信息再展开排查，思路和方向是一致的。