Docker 跨架构容器说明：ARM64 上遇到 exec format error 怎么处理

本文为通用排查说明，不代表本站已经在所有 ARM64 设备上验证每一种镜像。对长期运行的服务，优先选择原生支持目标架构的镜像。

为什么会出现 `exec format error`

当宿主机是 arm64，而镜像中的可执行文件只提供 amd64 版本时，容器启动阶段可能出现：

exec format error

这通常表示 CPU 架构不匹配，而不是应用配置文件写错。

先确认宿主机和镜像平台

uname -m
docker buildx imagetools inspect nginx:latest

对于自己构建的镜像，也可以在推送后用 imagetools inspect 查看清单是否同时包含 linux/amd64 与 linux/arm64。

长期方案：发布多架构镜像

如果项目依赖和基础镜像都支持目标平台，长期方案是用 Buildx 构建多架构镜像：

docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/your-name/your-app:latest \
  --push \
  .

这样 ARM64 设备拉取时可以获得原生镜像，不必长期依赖模拟执行。

临时兼容：使用 binfmt/QEMU

如果必须临时运行仅提供 amd64 的镜像，可以在明确了解风险后注册 binfmt 模拟支持：

docker run --privileged --rm tonistiigi/binfmt --install amd64

随后在 Compose 中显式指定平台：

services:
  app:
    image: your-amd64-only-image:latest
    platform: linux/amd64

这种方式适合验证或临时过渡。模拟执行会产生额外开销，具体影响取决于应用负载、宿主机和镜像内容；没有在目标设备上测量前，不应给出固定损耗比例。

应避免的做法

不要仅靠设置某个自定义环境变量来“绕过”CPU 架构不匹配；除非应用本身明确支持该变量，它无法让二进制变成另一种架构。
不要将模拟运行结果直接当作原生 ARM64 性能结论。
对数据库、模型推理或长期运行的服务，不应在未经测试时把 QEMU 作为正式部署默认方案。

参考资料

Docker 多平台构建：https://docs.docker.com/build/building/multi-platform/
Docker Buildx 文档：https://docs.docker.com/reference/cli/docker/buildx/

原先站内另外两篇同主题文章已建议取消公开，避免重复和相互不一致。