Hyperf在ARM64下报错大概率是镜像架构不匹配或运行时缺少跨架构支持，需用uname -m和docker buildx imagetools inspect确认宿主机与镜像架构是否均为linux/arm64，否则必现exec format error。
Hyperf 在 ARM64 镜像下报错，大概率不是框架问题，而是镜像构建时没对齐目标架构或运行时缺少跨架构支持。直接拉取 x86_64 镜像在 M1/M2 Mac 或 ARM 服务器上跑，必现 exec format error。
确认当前宿主机和镜像的架构是否匹配
先别急着改代码或重装扩展，用两行命令快速定位是不是架构错配：
- 查本地机器架构：
uname -m（ARM64 会输出aarch64或arm64；x86_64 是x86_64） - 查已拉取镜像支持哪些平台：
docker buildx imagetools inspect hyperf/hyperf:8.2-alpine-v3.19-swoole
如果输出里没有 linux/arm64，说明这个镜像压根不支持 ARM64 运行——哪怕你在 Apple Silicon 上 docker pull 成功了，也只是拉到了 manifest list，实际 layer 可能是空的或 fallback 到不兼容版本。
构建真正支持 ARM64 的 Hyperf 镜像
官方 hyperf/hyperf 镜像虽标称多架构，但部分 tag（尤其带 swoole 或 swow 的）在 ARM64 下缺少预编译扩展，需自行构建。关键不是“能不能编”，而是“用什么 base、怎么指定平台”：
- 基础镜像必须明确 ARM64 兼容：优先选
php:8.2-cli-alpine3.19（Alpine 官方已原生支持 ARM64），避免用php:8.2-cli-bullseye这类 Debian 系镜像，它在 buildx 下容易因 QEMU 模拟不稳定导致 swoole 编译失败 - 构建命令必须带
--platform：用docker buildx build --platform linux/arm64 -t my-hyperf-arm64 .，不能只靠docker build - Dockerfile 中 PHP 扩展安装要加架构判断：例如
apk add --no-cache php82-swoole（Alpine ARM64 包名与 x86_64 一致），但若用源码编译，需确保./configure --enable-swoole前已设好CC=aarch64-linux-musl-gcc
在 x86_64 主机上测试 ARM64 镜像的避坑点
很多团队想在 CI 的 x86_64 机器上构建并验证 ARM64 镜像，这时 exec format error 不是 bug，是缺 QEMU 支持：
- 必须启用 binfmt_misc：运行
docker run --privileged --rm tonistiigi/binfmt:latest --install all，否则docker run即使指定了--platform linux/arm64也会静默 fallback 到 host 架构 - buildx 构建器需显式创建：执行
docker buildx create --use --name multiarch-builder --driver docker-container，默认 builder 不启用多平台支持 - 验证时别用
docker run -it直接进 shell：ARM64 Alpine 的/bin/sh在 x86_64 上可能因 musl + QEMU 组合异常退出；改用docker run --platform linux/arm64 hyperf/hyperf:8.2-alpine-v3.19-swoole php -v这类无交互命令更可靠
Hyperf 启动阶段报错与架构的隐性关联
有些错误看似是配置或扩展问题，实则由架构差异触发：
-
Class "Swow\Socket" not found：Swow 官方未提供 ARM64 的 prebuilt .so，必须源码编译；但make过程中若检测到 host 是 x86_64，会误用 x86_64 工具链，需在 Dockerfile 中强制export ARCH=arm64并指定CC=aarch64-linux-musl-gcc -
failed to listen server port [0.0.0.0:9501]：M1 Mac 上 Docker Desktop 默认使用qemu-system-aarch64模拟 ARM64，但网络 stack 在模拟层有延迟，偶尔导致端口 bind 失败；可临时在config/autoload/server.php中加'sock_type' => SWOOLE_SOCK_TCP6绕过 IPv4/IPv6 混用问题 - 日志里出现
WARNING: The requested image's platform does not match the detected host platform：这不是致命错误，但说明你没在docker run时加--platform linux/arm64，Docker 正在降级运行，性能和稳定性不可控
真正的难点不在构建命令本身，而在于每层依赖（PHP、Swoole/Swow、Alpine、musl）是否都声明了对 ARM64 的完整支持——漏掉任意一环，都会在启动后某个随机时刻崩给你看。
