1. 前置条件
macOS 操作系统（Intel 或 Apple Silicon 均可）
Docker Desktop 已安装并正常运行（版本 ≥ 19.03，推荐最新版）
已注册阿里云账号并创建了命名空间（如 deanmr）
已登录阿里云镜像仓库（docker login --username=你的账号 registry.cn-beijing.aliyuncs.com）
2. 理解问题：为什么默认构建无法多平台？
在 macOS 上直接执行：
docker buildx build --platform=linux/amd64,linux/arm64 -t your-image --push .
会报错：
ERROR: multiple platforms feature is currently not supported for docker driver.
这是因为 Docker 默认的 buildx 驱动名为 docker，它仅支持单一平台构建。要同时构建多个架构，需要切换到 docker-container 驱动，该驱动利用 QEMU 模拟非本地架构。
3. 完整解决步骤
3.1 检查当前 builder 状态
打开终端，查看现有 builder：
docker buildx ls
输出示例：
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default docker default v0.11.7 linux/arm64
如果 default 节点的 DRIVER 为 docker，且 PLATFORMS 仅包含当前 Mac 的架构（如 linux/arm64），则说明不支持多平台。
3.2 创建新的 builder 实例（使用 docker-container 驱动）
创建一个名为 multiarch-builder 的新 builder，并立即切换使用：
docker buildx create --use --name multiarch-builder
--use：自动切换到新创建的 builder。
--name：自定义名称，方便管理。
该命令会自动使用 docker-container 驱动（多平台支持所需）。
3.3 启动并检查新 builder 支持的平台
docker buildx inspect --bootstrap
--bootstrap 会启动构建器容器，并输出详细信息。你应该看到类似：
Name: multiarch-builder
Driver: docker-container
...
Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6, linux/386, linux/ppc64le, linux/s390x
确保列表中包含 linux/amd64 和 linux/arm64。如果没有，请运行以下命令注册 QEMU 模拟器（通常 Docker Desktop 已内置，但可手动更新）：
docker run --privileged --rm tonistiigi/binfmt --install all
3.4 确认当前活跃的 builder
再次运行 docker buildx ls，看到 multiarch-builder 前有 * 标记，表示已激活：
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
multiarch-builder0 docker-container running v0.12.5 linux/amd64, linux/arm64, ...
default docker default v0.11.7 linux/arm64
3.5 构建并推送多架构镜像
假设你的项目根目录包含 Dockerfile，执行：
docker buildx build --platform=linux/amd64,linux/arm64 \
-t registry.cn-beijing.aliyuncs.com/deanmr/deantech:guac-gateway \
--push .
参数说明：
--platform：指定目标架构列表（amd64 和 arm64）。
-t：镜像标签，使用你的阿里云仓库地址。
--push：构建成功后直接推送到远程仓库。必须使用 --push，因为多架构清单无法通过 --load 加载到本地 Docker 引擎（--load 只支持单架构）。
3.6 观察构建过程
构建过程中你会看到：
同时拉取两个架构的基础镜像。
分别为 linux/arm64 和 linux/amd64 执行构建步骤（如 FROM, RUN, COPY 等）。
最后导出 manifest list（镜像清单）并推送。
注意：如果出现类似以下警告，可忽略（不影响成功）：
WARN: Requested platforms linux/arm64 do not match result platforms linux/amd64,linux/arm64
3.7 验证结果
方法一：查看 manifest 信息
docker manifest inspect registry.cn-beijing.aliyuncs.com/deanmr/deantech:guac-gateway
输出中 manifests 数组应包含两个条目，分别对应 "architecture": "amd64" 和 "architecture": "arm64"。
方法二：拉取测试
在 amd64 机器上执行：
docker pull registry.cn-beijing.aliyuncs.com/deanmr/deantech:guac-gateway
docker inspect | grep Architecture # 应显示 amd64
在 arm64 机器（如 Apple Silicon Mac）上拉取，则显示 arm64。
4. 日常使用与管理
4.1 切换 builder
切换回默认的 default builder：
docker buildx use default
再次切换回 multiarch-builder：
docker buildx use multiarch-builder
4.2 删除 builder（如不再需要）
docker buildx rm multiarch-builder
4.3 仅构建单架构（不推送）
若只需构建当前架构的镜像并加载到本地：
docker buildx build --platform=linux/amd64 -t myapp:amd64 --load .
5. 常见问题与故障排查
| 问题 | 解决方法 |
|---|
创建 builder 后执行构建依然报错 multiple platforms... | 检查是否确实切换了 builder：docker buildx ls，确保 * 在 multiarch-builder 上。 |
| 构建时卡在 pulling base image | 可能是网络问题，可配置镜像加速器（阿里云提供）。或者换用其他基础镜像源，如 docker.m.daocloud.io（你日志中已使用）。 |
| 推送失败，权限错误 | 确保已登录：docker login --username=你的用户名 registry.cn-beijing.aliyuncs.com。检查仓库命名空间是否存在。 |
| 在 Apple Silicon Mac 上构建 amd64 镜像非常慢 | QEMU 模拟有性能开销，属于正常现象。可考虑使用 GitHub Actions 等 CI 平台并行构建。 |
警告 Requested platforms ... do not match | 忽略，不影响最终产物。这是 buildx 内部检查的小 bug，后续版本可能修复。 |
6. 总结
通过切换至 docker-container 驱动的 builder，你可以在 macOS 上一键构建并推送多架构镜像（linux/amd64, linux/arm64）。核心命令如下：
docker buildx create --use --name multiarch-builder
docker buildx inspect --bootstrap
docker buildx build --platform=linux/amd64,linux/arm64 -t your-registry/image:tag --push .
之后任何架构的服务器拉取该镜像时，Docker 会自动选择匹配的版本。这极大简化了多平台应用的分发流程。
