使用 docker buildx 可一次性构建多架构镜像，需启用 builder、安装 qemu、指定 --platform 并加 --push 推送 manifest；go 编译应依赖 targetarch 而非硬编码 goarch，基础镜像选 debian 系以确保跨平台兼容性。
用 docker buildx 一次性构建多架构镜像
Go 程序本身跨平台编译容易，但容器镜像默认只构建当前宿主机架构（比如你本地是 AMD64，docker build 就不会生成 ARM64 镜像）。必须显式启用 buildx 并指定目标平台。
常见错误现象：镜像推送到仓库后，在树莓派或 M1 Mac 上 docker pull 成功但 docker run 报错 exec format error —— 这是典型的架构不匹配，不是镜像没拉全，而是根本没构建对应架构。
- 先检查是否启用 buildx：
docker buildx ls，若无buildxbuilder 实例，运行docker buildx create --use --name mybuilder - 启动 QEMU 支持（仅首次需要）：
docker run --privileged --rm tonistiigi/binfmt --install all - 构建时强制指定平台：
docker buildx build --platform linux/amd64,linux/arm64 -t yourname/app:latest --push . -
--push必须加，否则多架构镜像不会合并为一个 manifest；本地--load不支持多平台，会静默失败
Go 编译时避免硬编码 GOOS/GOARCH
Docker 构建中如果在 Dockerfile 里写死 GOARCH=arm64，会导致该镜像只能用于 ARM64，失去多架构意义。正确做法是让 Go 编译动作“跟随构建平台”。
使用场景：你希望同一份 Dockerfile 在 buildx 多平台构建时，自动适配目标架构的二进制，而不是每次改参数重写。
立即学习“go语言免费学习笔记（深入）”；
- 在
Dockerfile中用ARG TARGETARCH接收 buildx 传入的架构名（值为amd64或arm64） - Go 编译命令写成：
go build -o app -ldflags="-s -w" .（不指定GOARCH） - 关键点：Docker 构建阶段的基础镜像需支持多架构，例如用
golang:1.22-bookworm而非golang:1.22-alpine（Alpine 的交叉编译链不完整，ARM64 构建易失败） - 如需调试，可在构建时加
--progress=plain查看每阶段实际使用的TARGETARCH
验证镜像是否真含多架构 manifest
很多人以为 docker buildx build --platform 执行完就万事大吉，其实很容易漏掉验证环节。镜像仓库里看到的 tag 可能只是单个架构，或者 manifest 没推成功，导致下游拉取时 fallback 到本地匹配架构、而非远程统一分发。
典型错误：用 docker inspect 查看本地镜像，结果只看到一个架构 —— 因为 buildx 默认不 load 多架构镜像到本地 docker daemon。
- 查远程 manifest：
docker buildx imagetools inspect yourname/app:latest，输出中应有manifests数组，含多个platform字段 - 若报错
failed to do request，说明镜像没真正 push 成功，检查是否漏了--push或权限不足 - 不要依赖
docker images查架构，它只显示本地加载的那一个；也不要依赖 UI 控制台——很多私有 registry 不展示 manifest 结构
CI/CD 中 buildx 权限和缓存配置容易被忽略
本地跑通不等于 CI 里能跑通。GitHub Actions、GitLab CI 默认环境不启用 buildx，也常因缓存机制导致多平台构建复用错误中间层，最终镜像架构混乱。
性能影响明显：没有合理缓存时，ARM64 构建可能比 AMD64 慢 3–5 倍（尤其涉及 CGO 或大量依赖时）。
- GitHub Actions 必须显式启用 buildx：
docker/setup-buildx-action，且版本 ≥ v3 - 缓存需按
TARGETARCH分离：cache-from type=registry,ref=yourname/app:buildcache-${{ matrix.arch }} - 禁止在 multi-stage Dockerfile 中跨阶段混用
FROM --platform和无平台基础镜像，否则 buildx 可能误判依赖层级，跳过某架构的 stage - 私有 registry 若不支持 OCI manifest v2，
buildx imagetools会失败；此时需换用manifest-tool（已逐步淘汰）或升级 registry
最麻烦的点其实是：buildx 的错误信息非常不直观，failed to solve 这类提示背后可能是 QEMU 未注册、registry 认证过期、甚至 Docker daemon 版本太低（要求 ≥ 20.10）。遇到卡住，先查 docker buildx du -v 清缓存，再看 docker buildx inspect 输出里的 builder 状态。
