docker 镜像架构不匹配速查：exec format error 与 --platform 处置

更新时间：2026-10-24。FAQ 速查页，面向在 Apple Silicon、鲲鹏、树莓派等 arm64 机器上 docker run 直接报 exec format error、或拉镜像时被警告平台不匹配的同学。docker 镜像架构不匹配的本质一句话：镜像里的二进制是另一种 CPU 指令集编译的，内核 execve 时认不出文件格式，直接拒绝执行——容器甚至来不及启动，连一行日志都留不下。病灶收敛在六根轴上：拉到的镜像本身只有 amd64、manifest list 里没有本机架构、--platform 参数写错格式、buildx 构建时只产了单架构、QEMU binfmt 模拟没装好、镜像要求的指令集宿主机 CPU 太老不支持。镜像拉不下来的另一类限速问题看 docker pull 限速速查；容器能启动但运行期崩溃看 docker 容器段错误速查。

本文要回答的问题

• exec format error 与 no matching manifest for linux/arm64 分别对应哪一层的不匹配？
• --platform linux/amd64 强行跑 amd64 镜像为什么有时能跑、有时直接崩？
• 怎么确认一个镜像到底支持哪几种架构？
• 自己 build 的镜像在同事 M 系 Mac 上报格式错误，构建时要加什么参数？
• QEMU binfmt_misc 装了却还是不生效，差在哪一步？

一、报错原文与典型现象

架构不匹配有三张面孔，对应三个阶段（路径以 /proj/demo 占位，镜像源用 registry.example.com 占位）：

# 面孔一：运行期 exec 失败 —— 镜像拉下来了，但二进制格式本机不认
$ docker run --rm registry.example.com/legacy/tool:1.2
exec /entrypoint.sh: exec format error

# 面孔二：拉取期 manifest 缺失 —— 仓库里压根没有本机架构的镜像层
$ docker pull registry.example.com/legacy/tool:1.2
no matching manifest for linux/arm64/v8 in the manifest list entries

# 面孔三：拉取时的平台警告 —— 拉了 amd64 镜像，靠模拟硬跑
$ docker run --rm registry.example.com/legacy/tool:1.2
WARNING: The requested image's platform (linux/amd64) does not match
the detected host platform (linux/arm64/v8) and no specific platform was requested

读现象抓三条判据：exec format error 说明镜像层已落盘、容器已创建，死在内核 execve 那一刻，常见于 entrypoint 是 amd64 静态二进制而本机是 arm64；no matching manifest 死在更早的拉取阶段，说明镜像仓库的 manifest list 里根本没有本机架构这一档；WARNING: platform does not match 则说明你跑的是「跨架构模拟」，能起来不代表能稳——第三条会展开讲。想直接看镜像支持哪些架构，用 docker buildx imagetools inspect registry.example.com/legacy/tool:1.2，输出的 Platform 列表一目了然。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
run 时 exec format error	二进制与本机指令集不符	file 命令看二进制格式	换 arm64 镜像或 --platform 模拟
pull 时 no matching manifest	manifest list 缺本机架构	buildx imagetools inspect	换多架构镜像或自己 buildx 重出
WARNING platform mismatch	跨架构靠 QEMU 模拟	inspect 看 Image 的 Architecture	评估性能损耗，优先换原生镜像
模拟下跑一段后莫名崩	QEMU 模拟不全的指令	换原生镜像复现对比	弃模拟走原生构建
自建镜像只在本机可跑	buildx 只产单架构	imagetools 只列一种平台	buildx --platform 双架构重推
老服务器上新镜像起不来	镜像含 AVX 等新指令集	宿主机 cat /proc/cpuinfo 对 flags	用旧基线镜像或换编译选项
--platform 参数报错无效	平台串格式拼写错误	对照 OS/架构/变体三段格式	按 linux/arm64/v8 格式重写

三、排查决策图

这张图是标准排查路线：红是不匹配现象与命中的根因，蓝是排查动作，绿是验证通过，橙是修复，紫是防复发沉淀。

读这张图抓住分叉点：imagetools inspect 那一刀把问题切成两半——manifest 里有本机架构却被拉到错的，那是 --platform 或默认平台配置的问题；manifest 里压根没有，那是镜像供给侧的问题，要么换镜像、要么自己重出、要么接受模拟。两条路的成本和稳定性完全不同，别混着治。

四、逐条排查展开

镜像本身只有 amd64 是最常见的根因。 大量老镜像、内部工具镜像只推了 linux/amd64 一档。在 arm64 机器上 docker 会硬拉 amd64 镜像（给第三条那个 WARNING），之后容器内二进制全靠 QEMU 用户态模拟执行——hello world 级别能跑，一旦涉及 JIT、信号、线程库的边角行为，轻则慢十倍、重则直接崩。确认方式：

docker buildx imagetools inspect registry.example.com/legacy/tool:1.2
# 只看 Platform 行：只有 linux/amd64 就是单架构镜像
docker image inspect registry.example.com/legacy/tool:1.2 --format '{{.Os}}/{{.Architecture}}'

处置优先级：找官方多架构版本 > 自己用 buildx 出多架构 > 不得已才 --platform linux/amd64 模拟，且模拟只放开发环境，别进生产。

manifest list 缺架构死在拉取阶段。 与上一条相反，no matching manifest for linux/arm64/v8 说明 daemon 压根没拉镜像层——它先查 manifest list，发现没有任何一条匹配本机平台，直接拒了。这种情况 --platform linux/amd64 反而有效：显式告诉 daemon「我就要 amd64 那档，明知是模拟也拉」。命令形如 docker pull --platform linux/amd64 registry.example.com/legacy/tool:1.2，运行时同样带 --platform。

--platform 的平台串格式别拼错。 完整格式是 os/arch/variant 三段：linux/amd64、linux/arm64、linux/arm64/v8、linux/arm/v7 都合法；mac/arm、linux/aarch64/8 这类自创写法会直接报参数无效。写脚本或 compose 时平台串用引号包住，compose 里是 platform: linux/amd64 顶层字段。

自建镜像只产单架构是团队的坑。 本地 docker build 只产当前机器架构；同事换架构的机器一拉就是格式错误。正路是 buildx 一次双架构：

docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example.com/team/myapp:2.0 --push /proj/demo

注意 --push 与多架构绑定（多架构 manifest 只能直接推仓库，本地 images 存不住多档）；CI 里把这条固化进流水线，从此「在我机器上能跑」这句废话在架构维度也失效。

QEMU binfmt 没装好，模拟这条路直接断。 跨架构模拟依赖内核 binfmt_misc 注册 qemu 处理器。标准安装动作是 docker run --privileged --rm tonistiigi/binfmt --install all，装完 ls /proc/sys/fs/binfmt_misc/ 应能看到 qemu-aarch64、qemu-x86_64 等条目。装了不生效常见于：宿主机重启后注册丢失（需要重装或固化进启动脚本）、容器内二进制需要的解释器与 qemu 版本不兼容。验证用一条最小命令：docker run --rm --platform linux/arm64 registry.example.com/base/alpine uname -m，输出 aarch64 即模拟链路通。

宿主机 CPU 过老是反向的不匹配。 新镜像编译时开了 AVX2、AVX-512 等指令集优化，老 CPU 不支持，表现是容器内进程一跑就 Illegal instruction（退出码 132）。这不是 arm/amd64 的问题，是 amd64 内部的代际差异。处置：换保守编译基线的镜像（如 ubuntu:20.04 系比最新滚动版保守）、或自行编译时把 -march 降到 x86-64-v2。

五、规范做法与预防

• 镜像选型先查 manifest：引入新镜像第一件事 buildx imagetools inspect，确认含团队全部目标架构。
• CI 固定双架构构建：--platform linux/amd64,linux/arm64 --push 进流水线模板，单架构镜像禁止推生产仓库。
• 模拟仅限开发环境：生产与压测环境禁止 --platform 跨架构模拟，性能损耗不可预期。
• binfmt 注册进装机脚本：需要模拟的开发机，binfmt 安装命令写进初始化脚本，重启自动恢复。
• 编译基线显式声明：自建镜像注明目标指令集基线（如 x86-64-v2），避免新机器编出的镜像老机器跑不了。
• 平台串进 compose 规范：compose 文件里 platform 字段显式写出，不依赖 daemon 默认值漂移。

这一篇在知识体系里的位置

本篇是 docker 排错速查簇的架构平台篇，定位「容器死于 execve 之前、一行日志都留不下」：拉取阶段的网络与限速问题看 docker pull 限速速查；容器起来后运行期崩溃（退出码 139）看 docker 容器段错误速查；镜像内缺库缺文件的启动失败看 docker 路径不存在速查；与本篇同批的镜像内依赖精简问题看 docker 镜像缺运行依赖速查、命名冲突问题看 docker 容器名与端口冲突速查。manifest 判读、buildx 双架构、QEMU 模拟边界，是跨架构团队的基本功。

一句话总结

docker 架构不匹配分三层认脸：拉取期 no matching manifest 是仓库里没本机架构这一档（用 buildx imagetools inspect 验），运行期 exec format error 是二进制指令集不认（镜像已落盘、死于 execve），启动时的 platform WARNING 是在靠 QEMU 模拟硬跑（开发可用、生产禁用）。处置优先级永远是换原生多架构镜像 > buildx --platform linux/amd64,linux/arm64 --push 自出双架构 > 显式 --platform 模拟兜底；Illegal instruction 是 CPU 指令集代际问题，降编译基线解决。把双架构构建固化进 CI、镜像引入先查 manifest，这类问题就能从「玄学报错」变成选型时的前置检查项。