多阶段构建需配合buildx实现多架构编译：为每个架构（如amd64、arm64）定义独立命名阶段，使用带架构后缀的基础镜像，通过--platform参数触发对应阶段构建，最终生成多架构镜像清单或按需复制产物。
多阶段构建本身不直接解决多架构编译问题，但它可以和 buildx 配合，在单个 Dockerfile 中为不同 CPU 架构（如 amd64、arm64、ppc64le）分别构建、验证并打包对应产物——关键在于“阶段命名 + 架构感知构建上下文 + 条件复制”，而不是让一个阶段输出多个架构的二进制。
明确区分构建阶段与目标架构
每个架构应有独立的构建阶段（用不同名字），避免混用。比如：
-
builder-amd64：基于
golang:1.21-amd64编译 x86_64 二进制 -
builder-arm64：基于
golang:1.21-arm64编译 aarch64 二进制 -
builder-s390x：基于
golang:1.21-s390x编译 s390x 二进制
注意：基础镜像标签必须显式带架构后缀（如 golang:1.21-amd64），不能依赖默认 tag —— 否则 buildx 可能拉错镜像或失败。
用 buildx 构建时指定平台并触发对应阶段
Docker Buildx 是实现多架构的关键工具。它会在构建时根据 --platform 参数自动匹配对应 stage 的基础镜像，并只执行该平台相关的构建逻辑：
- 运行
docker buildx build --platform linux/amd64,linux/arm64 -t myapp . - Buildx 会为每个平台单独执行一次构建流程，分别进入
builder-amd64和builder-arm64阶段 - 各阶段生成的产物（如
/app/myapp-amd64、/app/myapp-arm64）互不干扰
运行阶段按需复制对应架构产物
最终镜像通常不包含所有架构二进制，而是做成“多架构镜像”（manifest list），或由运行阶段动态选择：
- 若目标是生成一个支持多平台的镜像列表（推荐），就不用在运行阶段复制二进制，而是用
buildx自动推送到 registry，由 manifest list 聚合各平台镜像 - 若需单镜像内含多架构可执行文件（如调试/兼容场景），可在运行阶段用
COPY --from=builder-amd64和COPY --from=builder-arm64分别复制，并加后缀区分 - 也可结合
ARG TARGETARCH在运行阶段做条件判断：RUN if [ "$TARGETARCH" = "arm64" ]; then cp /tmp/myapp-arm64 /usr/local/bin/myapp; fi
避免常见陷阱
几个容易出错但影响构建成败的细节：
- 不要在同一个 builder 阶段里用
GOOS=linux GOARCH=arm64 go build模拟交叉编译——某些 Cgo 项目会失败，且无法利用原生架构的性能和缓存 - 不要省略 stage 名称（如
AS builder写成AS builder-arm64），否则--from=无法精准引用 - 不要在运行阶段使用未声明的 stage 名；buildx 不会为你“猜”哪个阶段对应哪个平台
- 确保 CI 环境已启用
buildx并配置好 QEMU（用于非本机架构模拟），否则 arm64 阶段会直接报错
