必须显式创建并启用 buildx builder、指定 --platform 参数、使用 --push 推送，且 Dockerfile 中避免硬编码 GOARCH，才能成功构建多架构镜像。
直接用 docker buildx build 就能生成多架构镜像，但默认不启用 buildx、不配置 builder、不指定平台，就一定会失败——不是报 error: failed to solve: rpc error: code = Unknown desc = no valid drivers found，就是构建完只出一个架构。
buildx 没启用或 builder 不存在
新装 Docker（尤其是 Desktop for Mac/Windows）默认不启用 buildx，docker buildx ls 可能只显示 default 且状态为 inactive。必须显式创建并启用 builder：
- 运行
docker buildx create --use --name mybuilder --bootstrap，其中--use表示设为当前默认 builder，--bootstrap确保立即启动 - 再执行
docker buildx ls，确认mybuilder状态是running，且PLATFORMS列包含linux/amd64,linux/arm64 - 如果提示
qemu-user-static未注册，运行docker run --rm --privileged multiarch/qemu-user-static --reset -p yes（仅首次需要）
构建命令必须显式指定 --platform
即使 builder 支持多平台，docker buildx build 也不会自动推断目标架构——不写 --platform，它就只构建当前宿主机架构（比如你在 M1 Mac 上跑，默认只有 linux/arm64）：
- 正确命令：
docker buildx build --platform linux/amd64,linux/arm64 -t yourname/app . --push -
--platform必须写全，不能简写为amd64,arm64；顺序无关，但缺一不可 - 加
--push才会真正推送到镜像仓库；若只想本地构建，改用--load，但注意：--load不支持多平台，只能加载单个架构（通常为当前机器架构），所以多架构场景下基本必须--push
Go 编译阶段要适配交叉构建
Docker 构建时，Go 的 CGO_ENABLED=0 和 GOOS=linux 是基础，但跨架构还依赖 GOARCH ——而 buildx 会在每个平台上下文中自动设置它，你只需确保 Dockerfile 中没硬编码：
立即学习“go语言免费学习笔记（深入）”；
- ✅ 正确写法（交给 buildx 控制）：
FROM golang:1.22-alpine AS builder WORKDIR /app COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -o app .
- ❌ 错误写法（覆盖 buildx 设置）：
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o app .——这会让 arm64 构建也强行编译成 amd64 二进制，运行时报exec format error - 如果项目依赖 cgo（如 SQLite、OpenSSL），需提前在 builder 镜像中安装对应架构的交叉工具链，例如用
tonistiigi/binfmt注册 qemu 或换用rust-cross类多平台 builder 镜像
最容易被忽略的是：buildx builder 的生命周期独立于 Docker daemon，重启 Docker 后，自定义 builder（如 mybuilder）可能丢失或变为 inactive，每次 CI 脚本或本地重试前，最好先 docker buildx inspect mybuilder || docker buildx create --use --name mybuilder --bootstrap 做兜底。
