长亮不灭最近一个项目要把服务部署到一套 ARM 架构的服务器上，我手边只有一台 x86 的 Windows 笔记本。第一次我直接在 Dockerfile 里写好构建逻辑，以为镜像拉过去就能跑，结果目标机器上直接丢出一个 exec format error。那一刻我才意识到：构建镜像的宿主架构，会直接决定镜像是给谁用的、能不能跑。这篇文章就来聊清楚，在 Windows 操作系统上如何构建出 ARM 架构的 Docker 镜像：需要什么前置条件、Buildx 这套工具链怎么搭、跨架构构建的完整命令是什么，以及我在实际项目中踩过的那些坑。
这套方案对纯 x86 环境、但部署目标在 ARM 设备上的开发者特别有用。无论你是要把服务发到树莓派、国产生态服务器，还是给 Apple Silicon 用户做演示镜像，思路都一样：在 Windows 本机上用 Docker Buildx + QEMU 模拟，构建出 ARM64 的镜像并推送到仓库或导出成 tar 包，最终在 ARM 目标机上直接使用。
1. 先想明白：为什么要在 Windows 上构建 ARM 镜像
1.1 典型的落地场景：x86 开发与 ARM 部署之间的断层
很多团队面临的情况是：开发机清一色 Windows + x86，但测试环境、生产环境却是 ARM 架构。以前遇到这种需求，大家的第一反应是找一台 ARM 服务器专门做构建，或者把打包任务交给 CI 里的一台 ARM Runner。但现实往往没这么理想——ARM 构建机资源紧张、排队时间长，或者压根就没有专门的 ARM CI 节点。
这时候如果能直接在 Windows 开发机上完成跨架构镜像构建，流程会顺畅很多。我实际遇到过的场景大概有三种：
- 内部服务要交付给客户，客户的服务器是 ARM，但团队这边只有 x86 开发环境。
- 做一个通用的 Docker 镜像，同时要支持 amd64 和 arm64，让不同架构的用户拉取后都能直接跑。
- 开发阶段早期需要快速出一个 ARM 镜像包，临时在开发机上验证，不想为了一个小需求专门跑一趟 CI。
第三个场景最容易被忽视。很多人觉得跨架构构建是 CI 的事，本地不用管；但我发现，如果本地能直接构建 ARM 镜像，很多抽象的兼容性问题可以提前暴露，不用等 CI 跑到一半才报错。
1.2 Docker 镜像与 CPU 架构的关系：manifest 与平台自动选择
先理清楚一个基本概念：Docker 镜像里面装的不是纯文本，而是可执行的文件系统。这个文件系统里的二进制程序，是为特定 CPU 指令集编译的。x86 的 CPU 跑 x86 的程序没问题，跑到 ARM 的 CPU 上就是鸡同鸭讲，内核加载时会报 exec format error，这正是我开头遇到的那个错。
为了一次性兼容多架构，Docker 引入了 manifest list（也叫 OCI index）机制。简单来说，一个镜像 tag 可以对应多个不同平台的 manifest，每个 manifest 指向一份真正匹配该平台的镜像层。当你执行 docker pull 或者 docker run 时，Docker 客户端会根据当前机器的架构自动选择对应的 manifest，拉取正确的镜像层。
常见的平台标识是 linux/amd64、linux/arm64，Buildx 也支持 linux/arm/v7 这种 32 位 ARM 标识。不同平台在 Docker 生态里的地位差异很大，这里列一个最简单直观的对照：
| 平台标识 | 常见设备 | 备注 |
|---|---|---|
| linux/amd64 | 绝大多数 PC、云服务器 | Docker 生态里最“默认”的平台 |
| linux/arm64 | 树莓派 64 位系统、ARM 云服务器、Apple Silicon | 目前 ARM 部署的主流形态 |
| linux/arm/v7 | 树莓派 3/4 的 32 位系统、部分开发板 | 老设备仍在使用，但比例在下降 |
理解了这一点，你就能明白：所谓“构建 ARM 镜像”，本质上是在 x86 的 Windows 机器上，生成一套运行目标为 linux/arm64 的镜像层。难点不在于写 Dockerfile，而在于如何在构建过程中让基础镜像、依赖安装、编译动作都按照 ARM 的目标来执行。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：把 Windows 变成一台能跨架构构建的工作台
2.1 Windows 侧的前置条件：Docker Desktop 与 WSL2
构建跨架构镜像这种事情，单靠 Windows 容器是搞不定的。Windows 容器跑的是 Windows 内核，跟 Linux 容器完全是两套体系；而我们日常构建的绝大多数业务镜像都是 Linux 基础镜像。因此，第一步是确保 Docker Desktop 已经切到 Linux 容器模式，并且后端用的是 WSL2。
Docker Desktop 的默认安装一般会帮你配好 WSL2，你可以用一条命令验证一下：
bash复制docker info
输出里找到 Server Version 和 Operating System 字段，如果 Server 端是 Linux，并且 Kernel 路径指向 WSL2 的内核，那就没问题。如果还在用 Hyper-V 的老后端，我建议还是切成 WSL2：构建速度更快，资源占用也更合理，对 Buildx 的兼容性也更好。
2.2 创建支持多平台构建的 Builder 实例
很多初学者在 docker buildx 上翻的第一个车，是直接用了默认的 builder。Docker Desktop 默认的 builder 名为 desktop-linux，driver 是 docker。它的问题在于：走的是当前 Docker 引擎作为构建后端，不支持一次构建导出多个平台，也没法很好的处理“目标平台与宿主平台不一致”的情况。
解决方法是新建一个独立的 Buildx builder，并指定 driver 为 docker-container：
bash复制docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap
docker buildx ls
第一条命令创建了一个名为 multiarch 的 builder，--use 表示立即切换过去。第二条命令会启动这个 builder，并确认它已经正常运行。第三条命令可以查看当前所有 builder 以及它们支持的平台列表，我通常会确认 multiarch 这一行里包含 linux/arm64。
默认 builder 和新建的 docker-container builder 有什么区别？
| 维度 | desktop-linux（默认） | multiarch（docker-container） |
|---|---|---|
| 构建后端 | 当前 Docker 引擎 | 独立的 BuildKit 容器 |
| 多平台导出 | 不支持 | 支持 |
| 与本机 Docker 引擎交互 | 直接集成 | 需要通过 push 或导出 tar |
| 适合场景 | 普通业务镜像构建 | 跨架构、多平台镜像构建 |
这里要理解一个底层逻辑：docker-container driver 每次构建都会启动一个独立的 BuildKit 容器，这个容器里可以有独立的平台环境模拟能力，因此才能正常处理 --platform linux/arm64 这类参数。代价是构建结果不会直接出现在本机 docker images 里，后面会讲到怎么处理。
2.3 注册 QEMU 模拟器：让 x86 环境能执行 ARM 指令
构建 ARM 镜像时，往往不只是把文件打包，还需要在容器里执行命令，比如 apt-get install、pip install、npm install。这些命令本身是“目标架构”的二进制程序，x86 的宿主内核默认无法直接执行。为了跑起来，Linux 有一个机制叫 binfmt_misc：当内核识别到某个 ELF 文件的架构不是本机架构时，会自动调用对应的解释器。这里的解释器就是 QEMU 用户态模拟器。
注册 QEMU 模拟器的标准做法是：
bash复制docker run --privileged --rm tonistiigi/binfmt --install all
这条命令会下载并安装所有常见架构的 QEMU 模拟器注册信息。注册完成后，BuildKit 在执行 linux/arm64 阶段时，如果遇到需要运行的命令，就会通过 QEMU 把它翻译执行，让整个构建过程顺利走下去。
对于 Docker Desktop 的较新版本，QEMU 支持可能已经内置了一部分，但手动执行这条命令仍然是最稳妥的做法，尤其在 CI 或升级 Docker 之后容易遗漏。
3. 核心实操：构建一个 ARM64 镜像的完整过程
3.1 最小可验证的 Python 示例
为了让你完整体验一遍流程，我拿一个最简单的 Flask 应用举例。先准备项目文件：
python复制# app.py
from flask import Flask
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello, ARM64 Docker!"
text复制# requirements.txt
flask>=3.0
gunicorn>=21.2
dockerfile复制# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 8000
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]
这个 Dockerfile 很普通，关键在基础镜选择。python:3.12-slim 官方仓库同时发布了 amd64 和 arm64 的 manifest，这就是它能被用于跨架构构建的前提。
接下来执行跨架构构建：
bash复制docker buildx build --platform linux/arm64 -t demo/flask-app:arm64 --push .
解释几个关键参数：
--platform linux/arm64：告诉 BuildKit，目标平台是 ARM64。-t demo/flask-app:arm64：设置镜像名称和 tag。--push：构建完成后直接推送到远程镜像仓库。
为什么要 --push 而不是 --load？因为 --load 是把镜像加载到当前 Docker 引擎里，而当前引擎是 x86 的，加载一个 ARM64 镜像进去既没有意义也往往会报错。稍后我会专门讲这个坑。
执行过程中，你会看到 BuildKit 先拉取 python:3.12-slim 的 arm64 版本，然后在容器里执行 pip install。由于 QEMU 模拟的存在，这个阶段会比平时慢不少，耐心等待。构建完成后，镜像就会出现在你的镜像仓库里，可以拉到任何 ARM64 设备上运行。
3.2 一条命令同时发布 amd64 和 arm64
如果你的产品同时要交付给 x86 和 ARM 用户，更合理的做法是一次构建生成两个平台的镜像，并打包成一个 manifest list 推送到仓库。命令如下：
bash复制docker buildx build --platform linux/amd64,linux/arm64 -t demo/flask-app:latest --push .
这样推上去之后，demo/flask-app:latest 这个 tag 就包含了两个平台。用户在 x86 机器上拉取时，Docker 自动选择 amd64 的 manifest；在 ARM 机器上拉取时，自动选择 arm64 的 manifest。对使用者来说完全透明，体验非常好。
要注意的是，多个平台同时构建意味着每一层都要分别构建和推送，构建时间和网络流量都会成倍增加。我建议在正式发布或 CI 里才做这种多平台合并构建，本地调试阶段还是先用单平台模式，速度能快不少。
3.3 离线交付：把 ARM 镜像导出成 tar 包
有些场景不适合走镜像仓库，尤其是客户在内网环境、不允许连接外网仓库的时候。这种情况下，可以直接把构建结果导出成一个 tar 文件：
bash复制docker buildx build --platform linux/arm64 -o type=docker,dest=flask-app-arm64.tar .
注意这里使用了 -o 参数，指定输出类型为 docker，目标文件是 flask-app-arm64.tar。命令执行完成后，当前目录下就会多出一个 tar 包。把这个包拷到 ARM 服务器上，执行：
bash复制docker load -i flask-app-arm64.tar
镜像就会被加载到目标机器的 Docker 引擎里，随后正常 docker run 即可。
还有一个变体是 -o type=oci,dest=...，生成的是 OCI 格式的 tar 包，一般配合 docker load 在新版本 Docker 上也能加载。但对于兼容性要求比较高的场景，我仍然习惯用 type=docker。
4. 最容易翻车的几个坎：排错与经验
4.1 慢，是跨架构构建的第一冲击
第一次跑跨架构构建的人，十有八九会被速度吓到。QEMU 用户态模拟不是天衣无缝的性能等价，它要把 ARM 指令逐条翻译成 x86 指令执行，效率会打不少折扣。我实测下来，一个需要编译原生代码的镜像，构建时间可能是 x86 原生构建的 5 到 10 倍；即使是最简单的 pip install，也会明显感觉到延迟。
应对方法有两个层面。第一个是减少在模拟环境里执行的操作：尽量把构建阶段拆干净，能用缓存的地方用缓存。比如上面的 Python 示例，我把 requirements.txt 单独复制并安装，就是为了让依赖层独立缓存，业务代码一变，依赖层不用重装。
第二个方法是“能用交叉编译就用交叉编译”。这一点我会在下一个小节详细说，对于 Go、Rust、C/C++ 这类编译型项目，完全可以让编译器在本机架构下直接产出目标架构的二进制，而不是把整个编译过程放进 QEMU 里模拟。
4.2 编译型项目的正确处理方式：多阶段构建与交叉编译
如果你的项目是 Go 写的，跨架构构建有一个更专业的做法，几乎可以避开 QEMU 模拟的缓慢。下面这个 Dockerfile 是我在 Go 项目里常用的：
dockerfile复制FROM --platform=$BUILDPLATFORM golang:1.22-alpine AS build
ARG TARGETOS
ARG TARGETARCH
ENV GOOS=$TARGETOS GOARCH=$TARGETARCH CGO_ENABLED=0
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /out/app .
FROM --platform=$TARGETPLATFORM alpine:3.20
COPY --from=build /out/app /usr/local/bin/app
ENTRYPOINT ["app"]
这里有几个知识点需要讲透：
BUILDPLATFORM表示构建机本身的平台，这里就是linux/amd64。第一个 stage 用--platform=$BUILDPLATFORM拉取 amd64 的 golang 镜像，整个编译过程在原生 x86 环境里跑，速度飞快。- BuildKit 会在构建时自动注入
TARGETOS和TARGETARCH这两个环境变量，它们分别等于构建命令里--platform参数的 os 和 arch 部分，比如linux和arm64。 - 通过
GOOS、GOARCH环境变量，Go 编译器直接在本机交叉编译出 ARM64 的二进制文件，完全绕开模拟。 - 第二个 stage 用
--platform=$TARGETPLATFORM拉取 arm64 的 alpine 镜像，但这里只是把编译产物复制进去，不执行任何 RUN 指令，所以不存在性能问题。
但这里有一个大前提：项目必须启用了 CGO_ENABLED=0，也就是不依赖 C 库，纯静态编译。如果你的项目必须使用 CGO，比如要链接某个原生 C 库，那么这条路走不通，只能老老实实放到 QEMU 模拟里跑，或者找一台真正的 ARM 机器来编译。
类似的思路也适用于 Node.js 的项目，但稍微复杂一些：如果 npm install 过程中有 node-gyp 编译原生模块的步骤，在 QEMU 模拟环境里需要确保编译链齐全，比如 make、g++、python3 都存在，否则会报各种奇怪的编译错误。官方常见做法是使用 node:20-slim 作为构建基础镜像，它自带大部分工具链。如果预编译二进制下载阶段硬编码了 x86_64 版本的包，那就需要改下载链接，指向 arm64 版本，这个节点很多人容易漏掉。
4.3 --load 的边界：为什么本地加载 ARM 镜像总是出问题
我在很多群里看到有人提问：“明明构建成功了，为什么 docker images 里没有？”或者是“加载进去了，但一运行就报 exec format error。”这两种情况基本都是 --load 惹的祸。
--load 的作用是把构建产物加载到当前 Docker 引擎，但这个操作有一个隐含限制：它只能加载与当前引擎所在平台一致的镜像。在 x86 的 Windows 本机上，--load 一个 ARM64 镜像，通常会被 BuildKit 拒绝，报错信息大致是说不支持把 linux/arm64 平台导出到当前 Docker daemon。即使某些版本能加载进去，当你用 docker run 启动时，Docker 会尝试在 x86 内核上执行 ARM64 程序，最终还是 exec format error。
所以我的建议非常简单：在 Windows 本地上想验证 ARM 镜像，不要执着于 docker run，而是走“推送仓库”或“导出 tar 包”的路子，然后到真正的 ARM 设备上验证。如果只是想在构建机上快速确认构建产物有没有问题，用 docker buildx imagetools inspect 检查 manifest 就够了，这个命令我在后面会展开。
4.4 基础镜像与预编译二进制没有对应架构
跨架构构建的另一个常见报错是：
text复制no matching manifest for linux/arm64 in the manifest list entries
意思是说，你指定的基础镜像压根就没有发布 arm64 版本。这在太老的镜像、内部私仓里的历史镜像、或者某些个人维护的小众镜像中经常出现。
处理方式有两个方向：一是换一个官方维护的多架构基础镜像，或者升级到支持 arm64 的版本；二是自己构建一个 arm64 版本的基础镜像，作为中间产物使用。对大多数项目来说，换官方镜像是最省力的方案。在选型时，可以用这条命令快速查看某个镜像支持哪些架构：
bash复制docker buildx imagetools inspect python:3.12-slim
输出里会列出一大串 Platform，能看到 linux/amd64、linux/arm64 就说明支持。
除了基础镜像，还要留意 Dockerfile 里下载的预编译二进制包是否匹配目标架构。常见的一个坑是：在 Dockerfile 里直接写死了 wget https://xxx/xx-linux-x64.zip，下载的是一个 x86_64 的包。在 QEMU 模拟跑 apt install 可能没问题，但当你直接 ./xx 执行这个二进制时就会爆出 exec format error。排查方式很简单：在运行二进制的那条 RUN 指令里先执行 uname -m 看当前模拟环境的架构，再去检查下载包的平台后缀。
这里我习惯用一个排查表格，把常见现象和原因对应起来：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
运行时 exec format error |
镜像里的二进制是 x86 架构 | 下载 arm64 版本或重新编译 |
构建时 no matching manifest |
基础镜像不支持 arm64 | 更换多架构基础镜像 |
构建成功但本地 docker run 失败 |
--load 到 x86 引擎跑 arm64 镜像 |
推送到仓库或导出 tar 包，到 ARM 机验证 |
npm install 失败 |
原生模块在 QEMU 下缺少编译工具 | 安装 make/g++/python3，或交叉编译依赖 |
5. 验证与交付：从“构建成功”到“确定能跑”
5.1 在构建机上检查多架构清单
构建成功并不代表万事大吉，尤其是多架构合并构建的场景，你需要在构建机上确认“镜像清单”里的内容是否符合预期。用这个命令：
bash复制docker buildx imagetools inspect demo/flask-app:latest
输出会显示：
text复制Name: docker.io/demo/flask-app:latest
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest: sha256:...
Platforms:
linux/amd64
linux/arm64
只要看到 Platforms 下同时有 linux/amd64 和 linux/arm64，就说明多架构 tag 已经正确生成。如果只有单个架构，那八成是 --platform 参数只指定了一个目标，或者构建阶段里某个镜像不支持多架构导致被忽略。
5.2 在 ARM 设备上做最终的运行时验证
构建机的检查只能证明“镜像清单正确”，真正要证明“这个镜像能跑”，必须在 ARM 设备上跑一次。拿到 ARM 服务器或开发板后，可以按下面的顺序确认：
bash复制uname -m
如果输出 aarch64，说明当前系统就是 64 位 ARM。然后拉取镜像并运行：
bash复制docker run --rm demo/flask-app:arm64
如果服务正常启动，说明镜像本身没问题。还嫌不够的话，可以查一下镜像元数据里的架构字段：
bash复制docker image inspect --format '{{.Architecture}}' demo/flask-app:arm64
输出 arm64 就能确定这条路径完全正确。
在真实项目里，我通常还会加一步冒烟测试：进入容器执行一两个关键命令，比如 curl 本地接口或跑一条简单的数据库连接，确保不仅是启动成功，业务逻辑也正常。
5.3 把这套流程接进团队 CI
最后说一个进阶话题：当这套流程在本地验证稳定之后，把它固化到 CI 里是很自然的一步。GitHub Actions 上已经有成熟的 action 组合，可以非常简洁地完成跨架构构建：
yaml复制- name: Set up QEMU
uses: docker/setup-qemu-action@v3
- name: Set up Buildx
uses: docker/setup-buildx-action@v3
- name: Build and push
uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64
push: true
tags: your-repo/app:latest
这套 workflow 的思路和本地操作一模一样：先注册 QEMU，再配置 Buildx，最后指定多平台构建并推送。区别只是由执行器和缓存管理。如果你用的是 GitLab CI、Jenkins 或其他流水线，思路也是通用的，核心命令不外乎 docker run --privileged --rm tonistiigi/binfmt --install all 和 docker buildx build --platform ...。
把这些步骤接入 CI 之后，本地开发环境就可以卸载掉一大部分跨架构构建的负担，按需按量构建。但我这段时间实际用下来的个人体会是：本地能力仍然要保留，因为你不可能每次调试小问题都去触发一次 CI，本地十分钟内能看到结果，会大大缩短迭代反馈周期。
如果你也刚开始接触这套流程，我的建议是：本地先不要一上来就折腾多平台合并，先在默认 builder 下用 linux/amd64 把业务逻辑跑顺，确认没问题之后再切到 multiarch builder 做单平台 ARM 构建，最后才考虑多架构合并。我最初图省事，全程都走 QEMU 模拟，一个简单的 Python 服务构建花了大半个小时；后来把调试和正式构建分开，效率提升非常明显。另外，跨架构构建很容易积攒大量 BuildKit 缓存，偶尔执行一次 docker buildx prune，能帮你省出不少磁盘空间。