alpine下hyperf缺swoole、pcntl等扩展，因php:8.1-cli-alpine仅含最简php运行时，所有c依赖扩展均未预装；musl libc与glibc不兼容，无法复用debian/ubuntu的so文件；pecl install会因缺失构建链（如gcc、make）而失败；static-php-cli通过静态链接生成单二进制，彻底规避musl兼容性问题和容器内编译环境缺失风险。
为什么 Alpine 下的 Hyperf 总是缺 Swoole、pcntl 等扩展
因为 php:8.1-cli-alpine 镜像只带最精简的 PHP 运行时，所有依赖 C 编译的扩展（swoole、pcntl、openssl、mbstring）默认都不在。musl libc 和 glibc 不兼容，不能直接复用 Debian/Ubuntu 上编译好的 so 文件；pecl install swoole 会失败，报 ERROR: unsatisfiable constraints: swoole (missing) 或 configure: error: C compiler cannot create executables——本质是缺构建链，不是缺包。
用 static-php-cli 替代传统 pecl 安装流程
不走 apk add build-base → pecl install → docker-php-ext-enable 这条老路，改用 static-php-cli 直接产出单二进制，彻底绕过 musl 兼容性问题和容器内编译环境缺失风险。它把 PHP 解释器 + 所需扩展全部静态链接进一个可执行文件，启动快、无依赖、跨架构（ARM64/AMD64）天然支持。
- 必须显式指定扩展列表：
bin/spc build "swoole,curl,json,openssl,mbstring,pdo_sqlite"—— 漏掉swoole，Hyperf 启动直接报The ext-swoole is required - 加
--build-cli --build-micro参数才能生成php命令可用的二进制，否则只出php-cgi类型 - 编译过程需宿主机装好
gcc、make、autoconf等，但最终镜像里完全不需要这些工具链 - 生成的二进制体积比完整 PHP 小 60%+，适合边缘网关等资源受限场景
在 Dockerfile 中集成 static-php-cli 构建流程
别在运行时容器里编译，而是在构建阶段用多阶段 Dockerfile：第一阶段拉取 alpine:latest + 安装 static-php-cli 依赖并编译出 php 二进制；第二阶段只 COPY 二进制 + 项目代码，镜像大小可压到 20MB 以内。
关键点：
- 第一阶段必须用
alpine:latest（非php:xxx-alpine），否则spc识别 musl 版本失败 -
spc默认不启用pcntl，如需 Laravel 队列 fork 进程，得在 build 命令后加--enable-pcntl - 生成的二进制默认不加载
php.ini，需用PHP_INI_SCAN_DIR环境变量或-c参数指定配置路径 - Hyperf 的
bin/hyperf.php是纯 PHP 脚本，能直接被这个静态php二进制执行，无需任何修改
常见错误：编译成功但 Hyperf 启动报 extension not loaded
不是扩展没编进去，而是运行时没生效。典型表现：./php --ri swoole 显示已加载，但 ./php bin/hyperf.php start 仍报错。
- 检查是否漏了
swoole.use_shortname = Off—— 必须写进php.ini，静态二进制也认这个配置 -
./php -m | grep swoole为空？说明编译时没加swoole到 build 列表，或用了错误的 Swoole 版本（Hyperf v3.4+ 要求swoole >= 5.1.0） - 挂载本地代码进容器后，
bin/hyperf.php权限被 Windows 或 macOS 修改？加RUN chmod +x bin/hyperf.php更稳妥 - ARM 设备上运行 x86 编译的二进制？
file ./php看架构，确保spc build时指定了--arch aarch64
musl libc 的限制不是靠补依赖能绕过去的，静态编译是 Alpine 下 Hyperf 稳定运行的确定性解法。真正麻烦的不是编译本身，而是确认每个扩展是否真的被链接进二进制、以及运行时配置是否被正确读取——这两处最容易被忽略。
