the ext-swoole is required 错误表明 php cli 环境中完全缺失 swoole 扩展二进制（swoole.so），常见于 alpine 镜像等精简环境；需通过 static-php-cli 静态编译或 pecl install 显式安装并启用，且必须确保 cli 模式下 extension_loaded('swoole') 返回 true。
Hyperf 启动报 The ext-swoole is required，说明 PHP 环境里压根没加载 swoole 扩展——不是版本低、不是配置错，是根本不存在。这在 Alpine 镜像、精简 PHP 容器、或跳过扩展安装步骤时最常见。
为什么 php --ri swoole 会报错或直接不显示
常见现象：php --ri swoole 返回空、命令未找到、或提示 Extension 'swoole' not present。这不是 Hyperf 的锅，而是 PHP 运行时缺失该扩展的二进制模块（swoole.so）。
- Alpine 镜像（如
php:8.1-cli-alpine）默认不含任何 C 扩展，swoole必须手动编译安装 - Debian/Ubuntu 镜像若用
php:8.1-cli（非-slim），也只带curl、json等基础扩展，swoole仍需pecl install - Windows + WSL2 下若只装了 PHP CLI 包，没运行
pecl install swoole或没启用extension=swoole，同样缺失 -
docker-php-ext-enable swoole只对已编译好的.so文件生效；如果pecl install失败（比如缺gcc、make），那目录下根本没生成swoole.so
在 Alpine 容器中正确安装 swoole 扩展
别在运行时容器里跑 apk add build-base && pecl install swoole——musl libc 不兼容 glibc 编译的 so，且构建链体积大、易失败。推荐用 static-php-cli 静态编译：
- 构建阶段用多阶段 Dockerfile：第一阶段基于
alpine:latest（不是php:xxx-alpine），装build-base autoconf automake，再执行bin/spc build "swoole,curl,json,openssl,mbstring" - 必须加
--build-cli --build-micro参数，否则生成的是php-cgi类型，无法运行php bin/hyperf.php start - 漏掉
swoole在扩展列表里，生成的二进制启动 Hyperf 时仍会报The ext-swoole is required - 第二阶段镜像只 COPY 编译好的
php二进制 + 项目代码，无需任何构建工具，体积可压到 20MB 内
在 Debian/Ubuntu 容器或本地开发环境安装 swoole
确认 PHP 版本与 Swoole 兼容（例如 PHP 8.3 需 Swoole ≥5.1.5），再走标准流程：
- 先装系统依赖：
apt-get update && apt-get install -y libssl-dev zlib1g-dev g++ - 再装扩展：
pecl install swoole-5.1.5（显式指定版本，避免自动装错） - 启用扩展：
docker-php-ext-enable swoole（Docker）或手动在php.ini加extension=swoole - 验证：
php --ri swoole输出中必须有Version => 5.1.5和coroutine => enabled - 注意 CLI 和 FPM 的
php.ini是两个文件，确保你改的是 CLI 路径下的（常为/etc/php/8.3/cli/conf.d/20-swoole.ini）
检查 swoole 是否真被加载，而不仅是“存在”
即使 php --ri swoole 能输出信息，也不代表 Hyperf 就能用——可能 CLI 和 Web SAPI 加载了不同配置，或扩展被禁用。
- 在项目根目录运行：
php -m | grep swoole，看是否在启用模块列表里 - 写个临时脚本
test.php：<?php var_dump(extension_loaded('swoole'));，执行php test.php应输出bool(true) - 如果输出
false，检查php -i | grep 'Loaded Configuration File'确认当前生效的php.ini路径，再查该文件里是否有extension=swoole且未被注释 - 某些镜像（如
hyperf/hyperf:8.1-alpine-v3.16-swoole）已预装，但若你覆盖了php.ini或用了自定义入口，仍可能绕过加载
最容易被忽略的一点：Swoole 扩展必须在 CLI 模式下可用，而不仅仅是 FPM 或 Apache。Hyperf 启动命令 php bin/hyperf.php start 是纯 CLI 场景，跟 Web 服务无关。别只验证浏览器访问 phpinfo() 页面，得用 php -m 或 php -r 直接测 CLI 环境。
