“exec format error”本质是CPU架构不匹配，需从明确目标架构、选用支持该架构的多平台基础镜像、配置QEMU模拟或原生ARM构建环境三方面解决，关键操作包括添加--platform参数、验证镜像manifest、启用binfmt_misc。
遇到 FROM 指令报“架构不兼容”（如 exec format error、failed to solve: rpc error... 或构建时卡在 RUN 阶段），本质是 Docker 尝试在当前主机上运行一个与 CPU 架构不匹配的基础镜像层。这不是 Dockerfile 写错了，而是平台声明、基础镜像支持或本地环境没对齐。解决要从三个层面入手：明确目标架构、选对基础镜像、配好执行环境。
确认并显式声明目标架构
别依赖默认行为。Docker 27+ 的 BuildKit 默认严格校验 manifest，若未声明平台，它可能按宿主机推断，导致拉取错架构镜像。
- 在
docker build或buildx build命令中必须加--platform，例如：docker build --platform linux/arm64 -t myapp . - 在 Dockerfile 的
FROM行前加--platform=前缀（Docker 20.10+ 支持）：FROM --platform=linux/arm64 alpine:3.20 - 避免写死带架构后缀的标签（如
alpine:3.20-arm64），官方镜像不提供这种格式，会 404
验证基础镜像是否真支持该架构
不是所有标签都发布全架构。比如 alpine:3.20 可能缺 arm64，但 alpine:3.20.3 已补全。不能只看名字，要看 manifest 列表。
- 查支持的平台：
docker buildx imagetools inspect alpine:3.20 | jq '.manifests[].platform' - 如果输出里没有
linux/arm64，就换一个已知支持的版本，比如alpine:3.20.3或debian:12.6 - 优先选官方维护的多架构镜像：Alpine、Debian、Ubuntu、distroless 等主流镜像基本都支持
amd64和arm64
确保本地能运行目标架构的二进制
在 x86_64 机器上构建 arm64 镜像，RUN 指令里的命令（如 apk add）必须能在 ARM64 下执行——这需要 QEMU 模拟支持。
- 启用 binfmt 和 QEMU：
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes - 验证是否生效：
cat /proc/sys/fs/binfmt_misc/qemu-aarch64应显示enabled - 若跳过此步，RUN 会直接报
exec format error，且错误信息常被 BuildKit 隐藏（Docker 27 默认BUILDKIT_PROGRESS=plain）
用 buildx 创建专用多架构构建器（推荐用于 CI/CD）
单靠 --platform 参数有时不够稳定，尤其在复杂流水线中。buildx 可创建持久化构建器实例，自动管理 QEMU、缓存和跨平台调度。
- 初始化构建器：
docker buildx create --use --name mybuilder --platform linux/amd64,linux/arm64 - 启动并验证：
docker buildx inspect --bootstrap - 构建推送（自动处理 manifest list）：
docker buildx build --platform linux/amd64,linux/arm64 --push -t your-registry/app:latest .
