Intel Mac 构建 ARM64 Docker 镜像简记

文章目录

一、环境信息
二、升级 Docker Desktop
三、注册 QEMU 多架构模拟器
四、配置 Buildx 构建器
五、构建与验证
六、架构原理
七、重启恢复
八、常用命令
九、注意事项

最近需要在一台 Intel Mac 上给 ARM 服务器构建 Docker 镜像，记录一下完整流程。核心思路：Docker Desktop 升级到支持版本 → QEMU 模拟 ARM 指令 → Buildx 多架构构建。

一、环境信息

操作系统	macOS 13.7 Ventura (Intel x86_64)
Docker Desktop	4.47.0 (Build 206054)
Docker Engine	28.4.0
Buildx	0.28.0
QEMU	multiarch/qemu-user-static:latest

版本说明：Docker Desktop 4.48.0 起要求 macOS ≥ 14 Sonoma，macOS 13 最高可用 4.47.0。如果系统已升级到 14+，可以直接装最新版。

二、升级 Docker Desktop

旧版 Docker（19.x/20.x）的 buildx 功能残缺，--platform 和 docker-container 驱动基本不可用，必须先升级。

# 下载 4.47.0 Intel Mac 版（约 580MB）
curl -L -o /tmp/Docker-4.47.0.dmg \
  "https://desktop.docker.com/mac/main/amd64/206054/Docker.dmg"

# 停止旧版
osascript -e 'quit app "Docker"'

# 挂载并安装
hdiutil attach /tmp/Docker-4.47.0.dmg -noverify -nobrowse
cp -R /Volumes/Docker/Docker.app /Applications/
hdiutil detach /Volumes/Docker

# 启动
open -a Docker

三、注册 QEMU 多架构模拟器

QEMU 通过内核 binfmt_misc 机制拦截 ARM64 可执行文件，自动交给翻译器执行。这一步是整个方案的核心。

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

执行后会注册 aarch64、arm、riscv64 等 30 个架构的指令翻译器。验证：

docker run --rm --platform linux/arm64 alpine uname -m
# 输出 aarch64 表示成功

四、配置 Buildx 构建器

创建 docker-container 驱动的构建器实例，这是多架构构建的基础。

docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap multiarch

五、构建与验证

以一个包含 Python、Node、Flask、Express 的综合镜像做测试：

FROM alpine:latest
RUN apk add --no-cache curl wget git bash \
    python3 py3-pip nodejs npm build-base gcc
RUN pip3 install flask --break-system-packages
RUN npm install -g typescript express
CMD ["python3", "-c", "print('ARM64 OK')"]

docker buildx build --platform linux/arm64 --load -t arm64-test:latest .
docker inspect arm64-test:latest --format '{{.Architecture}}'
# 输出: arm64

测试结果：

uname -m	aarch64
Python 3.12	正常
Flask 3.1	正常安装运行
Node 24 + Express 5	正常安装运行
TypeScript 6.0	编译通过
gcc/g++	编译可用
网络 (pip/npm)	下载正常

六、架构原理

Intel Mac (x86_64)
  └── Docker Desktop (HyperKit VM)
        └── Linux VM (amd64 内核)
              ├── QEMU binfmt_misc  ← ARM64 指令翻译
              └── BuildKit (docker-container)
                    └── buildx build --platform linux/arm64
                          ──▶ ARM64 镜像

QEMU 在内核层面拦截 ARM 二进制文件，启动时自动切换翻译器。整个过程对 Docker 透明，无需修改 Dockerfile。

七、重启恢复

Mac 或 Docker 重启后 QEMU 注册会丢失（写入的是 VM 内核内存），一行恢复：

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Buildx 容器会自动重启，不需要额外处理。

八、常用命令

# 单架构构建（本地加载）
docker buildx build --platform linux/arm64 --load -t app:arm64 .

# 多架构构建（推送到 Registry）
docker buildx build --platform linux/amd64,linux/arm64 \
  --push -t username/app:latest .

# 查看构建器
docker buildx ls

# 查看镜像架构
docker inspect IMAGE --format '{{.Architecture}}'

注意：--load 只支持单平台，多平台必须用 --push。

九、注意事项

QEMU 模拟性能约为原生的 1/3~1/5，小型项目差异不大，大型编译建议用 CI/CD 跑原生 ARM 机器
容器内 DNS 可能异常，可在 Dockerfile 首行加 echo "nameserver 114.114.114.114" > /etc/resolv.conf 或配置 daemon.json
基础镜像建议用官方镜像，天然支持多架构（alpine/node/python 等）