技术 · 实用指南
Docker提示exec format error？先查镜像、二进制与入口，再决定重建
exec format error不能单凭镜像标签诊断。先追踪选中的清单、最终文件系统、可执行文件架构和入口解释器，再考虑清理缓存、添加QEMU或重建。
对Linux容器而言，“exec format error”表示内核无法执行收到的文件。CPU架构只是可能原因之一；缺少可用解释器头的脚本或其他无效可执行格式也可能失败。应先找出具体文件和失败阶段，再选择修复方法。
保留失败镜像和错误输出。一份有用的故障记录应串起四个环节：运行主机、选中的镜像清单、最终文件系统内的真实可执行文件，以及尝试启动它的命令。架构标签相符，并不能替代对这四项的核对。
1. 重建前记录失败运行
保存完整错误、镜像引用及摘要、已有容器ID、请求的平台和使用的Docker context。检查失败容器的配置与挂载，不要只看Dockerfile：运行时覆盖入口或挂载脚本，可能改变实际执行的文件。用docker container inspect CONTAINER取得配置，用docker image inspect IMAGE查看本地镜像元数据。
相关主机是实际执行进程的Docker守护进程或构建工作节点，可能在远端，也可能位于Docker Desktop的Linux虚拟机内。仅知道笔记本处理器不足以确定它。还应区分Dockerfile的RUN指令失败与成品容器启动失败：RUN阶段报错点名/bin/sh，应检查构建阶段环境；应用入口失败则需检查最终运行文件系统。
2. 对照仓库变体与本地镜像
用docker buildx imagetools inspect IMAGE_REFERENCE查看仓库引用的清单及平台变体，再与确切的本地镜像和失败运行请求的平台比较。可变标签可能在失败后指向新镜像，因此应保留原摘要，不要把今天的标签当成历史证据。
所需平台变体不存在时，应选择或构建正确变体；变体存在却选错时，检查显式平台设置与部署配置。--platform=linux/amd64是在指定目标，并不会转换已经复制进镜像的任意arm64文件。找不到兼容清单可能在执行前就产生选择错误，与ENOEXEC发生的阶段不同。
3. 不启动失败命令也能检查文件
如果已有停止的失败容器，可用docker cp CONTAINER:/path/to/file ./artifact-to-inspect复制可疑文件。Docker文档明确支持从停止的容器复制。如果只有镜像，docker create IMAGE会创建但不启动容器；记录返回ID，再检查这个临时容器。挂载需另外核对，因为运行时提供的文件可能不同于镜像内容。
用可信的文件检查工具（如file）检查复制出的文件；对ELF二进制，readelf -h可显示机器类型，readelf -l可显示其要求的程序解释器。检查文件本身，不要为了确定架构而执行它。本地没有这些工具时，使用已有可信分析环境。不要假定精简或distroless镜像内自带shell、file或readelf。
4. 沿构建阶段追查复制的二进制
列出所有会创建或下载可执行文件、并把它们复制进最终镜像的阶段。BUILDPLATFORM描述BuildKit工作节点，TARGETPLATFORM描述请求的输出。固定到构建主机平台的阶段可以有意运行原生编译器，但其编译设置仍须生成目标平台产物。
Docker预定义目标参数在全局可用，但在阶段内使用前须以ARG声明。检查TARGETOS、TARGETARCH及所需的TARGETVARIANT，再核对语言工具链真正生成的产物。只声明参数，不会让所有编译器自动交叉编译。同样，把最终FROM换成目标兼容基础镜像，也不会转换从另一阶段复制来的不兼容可执行文件。
5. 分开判断脚本、缺失解释器与权限
对直接执行的脚本，检查开头字节和解释器行：#!头须指向预期解释器，该解释器也必须存在于运行文件系统。留意头部之前的异常字节与Windows风格换行。显式通过shell启动会改变脚本的执行方式，并不能证明原先直接执行的路径已修复。
保留准确错误类别。Linux将无法识别格式或错误架构归为ENOEXEC；路径、脚本解释器或ELF解释器缺失属于ENOENT；执行权限被拒或noexec挂载等权限问题属于EACCES。因此，看得到文件也可能因解释器缺失而失败。chmod不能修复错误CPU架构，添加模拟执行也不会安装缺失的解释器。
6. 一次修一个原因，再验证原路径
依据证据选择分支：缺少变体就修镜像选择或构建输出；内含二进制错误就重建或替换该产物；脚本格式错误就修头部或编码；解释器缺失就提供所需兼容运行环境；权限拒绝就检查用户、文件模式与挂载策略。清理镜像不能代替确定故障分支。
模拟执行是有意运行非原生程序的一种选择。修改主机级binfmt注册前，先确认实际工作节点的支持情况；Docker Desktop与官方BuildKit可能已经提供模拟功能。修复后，在可丢弃的非生产环境，以相同预期命令、平台、用户及相关挂载测试。记录新摘要和具体改变的检查项。仍失败时保留新错误，从该失败层继续，而不是重复同一次重建。
