必须使用 docker buildx 实现多架构镜像构建，它基于 buildkit 和 qemu 模拟支持并发构建 amd64/arm64 镜像，并自动生成 oci manifest list；dockerfile 无需修改，只需确保基础镜像支持多架构且不硬编码架构相关路径。
直接用普通 docker build 只能生成当前宿主机架构的镜像，比如在 x86_64 机器上构建，结果必然是 linux/amd64。要真正让一个 Dockerfile 同时产出 X86（amd64）和 ARM（arm64）可用的镜像，必须依赖 Docker Buildx —— 它是官方支持的多平台构建工具，底层用 BuildKit + QEMU 模拟实现跨架构编译与打包。
确认 Buildx 环境已就绪
Buildx 不是默认启用的，需手动验证和初始化：
- 运行
docker buildx version，确保输出类似github.com/docker/buildx v0.12.1（2026 年推荐 ≥ v0.11.0） - 执行
docker buildx ls，检查是否有活跃 builder（带*标记）。若无，创建一个支持双架构的实例：docker buildx create --use --name mybuilder --platform linux/amd64,linux/arm64 - Linux 用户还需注册 QEMU 模拟器：
docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64
macOS/Windows 用户使用 Docker Desktop 4.15+ 通常已预装，无需额外操作
Dockerfile 本身无需为架构做特殊修改
绝大多数标准 Dockerfile（尤其采用多阶段构建的）天然兼容多架构，关键在构建方式而非写法。例如一个 Go 应用的典型结构：
- 第一阶段用
golang:1.22-alpine编译二进制，该镜像本身已发布 amd64/arm64 多架构版本 - 第二阶段用
alpine:3.20作为运行时基础镜像，同样原生支持双架构 - 只要不硬编码架构相关路径（如
/usr/lib/x86_64-linux-gnu）、不调用架构专属二进制工具，Dockerfile 就可复用
注意：避免使用 FROM ubuntu:22.04 这类未显式声明架构的标签——应优先选带 amd64/ 或 arm64v8/ 前缀的镜像（如 amd64/ubuntu:22.04），或确认上游是否提供 Manifest List。
用 buildx 命令触发双架构构建与推送
在 Dockerfile 所在目录执行以下命令，即可一次性构建并推送到镜像仓库：
docker buildx build --platform linux/amd64,linux/arm64 --tag your-registry/app:1.0 --push .
-
--platform明确声明目标架构，Buildx 会并发拉取对应架构的基础镜像、分别执行构建步骤 -
--push会自动上传两个架构的镜像层，并生成一个 OCI Image Index（Manifest List）指向它们 - 推送完成后，任意架构的机器执行
docker pull your-registry/app:1.0，都会自动下载匹配本地 platform 的那一份
验证镜像是否真正支持多架构
构建完成后，别只看本地 docker images —— 那只显示当前节点缓存的架构。正确验证方式是查远程仓库的 manifest：
- 用
docker buildx imagetools inspect your-registry/app:1.0（推荐，Buildx 自带） - 或调用 registry API：
curl -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \<br> https://your-registry/v2/app/manifests/1.0
- 返回 JSON 中若含多个
manifests条目，且platform.architecture分别为amd64和arm64，即成功
