docker buildx 构建多架构镜像的核心是通过单条 build 命令生成含多个平台镜像的 manifest list，依赖 qemu 模拟在 x86 上构建 arm64 等镜像；需启用实验功能、创建专用构建器、编写适配 targetarch 的 dockerfile，并用 --platform 指定目标架构推送至远程仓库。
用 Docker Buildx 构建多架构镜像，核心是让一个 docker buildx build 命令同时产出多个平台的镜像，并打包成统一标签的 manifest list。它不依赖你手头有没有 ARM 服务器或树莓派，靠 QEMU 模拟就能在 x86 机器上生成 arm64 镜像。
确认环境与启用多架构构建器
Buildx 从 Docker 19.03 起内置，但需手动激活：
- 运行
docker version，确保 client 和 server 版本均 ≥ 19.03 - 在
~/.docker/config.json中添加"experimental": "enabled" - 创建专用构建器：
docker buildx create --use --name multiarch-builder - 启动并加载模拟器：
docker buildx inspect --bootstrap（首次运行会自动注册 arm64、arm/v7 等 binfmt 支持）
编写能识别目标架构的 Dockerfile
光靠 --platform 不够，Dockerfile 得主动适配不同架构：
- 基础镜像加
--platform=$BUILDPLATFORM，例如：FROM --platform=$BUILDPLATFORM golang:1.23-alpine AS builder - 用
ARG TARGETARCH获取目标架构，在 RUN 中做分支处理，比如：RUN if [ "$TARGETARCH" = "arm64" ]; then apk add ca-certificates; else apt-get update && apt-get install -y curl; fi - 优先选用官方多架构基础镜像（如
alpine:latest、node:20-alpine），避免自建单架构镜像导致构建失败
执行构建并推送 manifest list
构建命令要明确指定平台、输出方式和仓库地址：
- 直接推送到远程 Registry（推荐生产用）：
docker buildx build --platform linux/amd64,linux/arm64 --push -t your-registry/myapp:v1.0 . - 推送前确保已登录：
docker login your-registry.example.com - 本地调试可用
--load加载到当前引擎（仅限本机架构），但无法验证跨平台拉取逻辑 - 加缓存提升重复构建效率：
--cache-from type=registry,ref=your-registry/myapp:v1.0-cache --cache-to type=registry,ref=your-registry/myapp:v1.0-cache,mode=max
验证生成的多架构清单
推送完成后，用 imagetools 检查是否真正生成了 manifest list：
docker buildx imagetools inspect your-registry/myapp:v1.0- 输出中应看到多个
platform条目，例如linux/amd64和linux/arm64，每个对应独立 digest - 在 ARM 设备上运行
docker pull your-registry/myapp:v1.0，会自动下载 arm64 层，无需改标签
