Docker 多架构镜像构建需通过 buildx 配合 QEMU 实现，先启用 buildx 构建器并注册 QEMU 模拟器，再用 --platform 指定目标架构、--push 推送生成 manifest list，最后用 imagetools inspect 验证。
在 Docker 中构建 Multi-Arch（多架构）镜像，核心是借助
buildx
构建器配合 QEMU 模拟器，实现一次定义、跨平台（如 amd64、arm64、arm/v7 等）构建与推送。原生
不支持多架构，必须启用并配置 buildx。
启用并配置 buildx 构建器
Buildx 是 Docker 官方推荐的下一代构建工具，已随 Docker Desktop 20.10+ 默认集成；Linux 用户需手动安装或启用：
检查是否可用：
（若报错，需安装 buildx 插件）
创建并切换到多节点构建器实例：
确认当前 builder 支持的平台：
，输出中应含
、
等
如缺少 arm64 等平台，需注册 QEMU：运行
编写支持多架构的 Dockerfile
无需特殊语法，但建议避免硬编码架构相关命令（如直接调用
）。关键点：
使用
显式指定基础镜像平台（可选，buildx 会自动匹配）
优先选用官方多架构基础镜像，例如：
（Alpine 官方已全量支持 arm64/amd64）
若需条件编译（如 Go 项目），可通过构建参数传入：
，Docker 会自动注入当前目标架构（
、
等）
执行跨平台构建与推送
使用
替代
，关键参数如下：
Docker Sandbox
创建并管理 Docker 沙箱虚拟机环境以安全执行代理。适用于运行不受信任代码、探索包或隔离代理工作负载。支持 Claude、Codex、Copilot、Gemini 和 Kiro 代理，并提供网络代理控制。
下载
：声明目标架构列表
：直接推送到镜像仓库（需提前
）
：标签将自动关联为 manifest list
完整示例：
成功后，远程仓库中该 tag 实际是一个
manifest list
，Docker pull 时会根据本地
自动拉取对应架构镜像。
验证与调试多架构镜像
构建完成后，快速验证是否生效：
查看 manifest list：
（显示各架构 digest 和 OS/Arch）
在不同设备上拉取测试：
— arm64 设备执行
→ 应自动获取 arm64 层
— amd64 主机同命令 → 获取 amd64 层
本地模拟某架构构建（不依赖物理设备）：
+
docker builddocker buildx versiondocker buildx create --name mybuilder --use --bootstrapdocker buildx inspect --bootstraplinux/amd64linux/arm64docker run --rm --privileged multiarch/qemu-user-static --reset -p yesapt-get install xxx-amd64FROM --platform=...FROM golang:1.22-alpine--build-arg TARGETARCHamd64arm64buildx builddocker build--platform linux/amd64,linux/arm64,linux/arm/v7--pushdocker login--tag yourname/app:latestdocker buildx build --platform linux/amd64,linux/arm64 --push --tag ghcr.io/yourname/app:1.0 .runtimedocker buildx imagetools inspect yourname/app:1.0docker pull yourname/app:1.0docker buildx build --platform linux/arm64 --load .docker run --rm --platform linux/arm64 ...