php --ri swoole是唯一可靠方式，必须检查Version、coroutine=>enabled、swoole.use_shortname=>Off三行，验证协程组件需用class_exists('Swoole\Coroutine\MySQL')等，CLI与FPM的php.ini均须启用extension=swoole.so。
php --ri swoole 是唯一可靠方式
别信 php -m | grep swoole 或 composer.json 里写的版本号，它们只告诉你扩展“装了没”，不反映真实运行时行为。真正要确认 Swoole 版本和协程状态，必须执行：php --ri swoole。输出里关键三行是：Version（如 5.1.5）、coroutine => enabled、swoole.use_shortname => Off —— 最后一项漏配会导致 Hyperf 启动直接报错。
检查 HTTP Server 构造参数是否兼容当前版本
如果你的代码里还用着 new Swoole\Http\Server('0.0.0.0', 9501, SWOOLE_BASE, true) 这种带第四个 $ssl 参数的写法，那基本可以断定 Swoole 版本低于 5.0 或高于 4.8.x 但未适配——因为 5.x 已移除该参数，而 4.8.x 起已废弃同步回调模式。实际应改为：
$server = new Swoole\Http\Server('0.0.0.0', 9501, SWOOLE_BASE);
$server->set(['ssl' => true]);
若启动时报 Fatal error: Uncaught Error: Call to undefined method，大概率就是构造参数签名不匹配。
验证协程组件是否存在且可用
光有 coroutine => enabled 不够，还得确认你用到的具体类在当前版本里真能加载。例如：
-
class_exists('Swoole\Coroutine\MySQL')必须返回true，否则数据库协程客户端会失效 -
class_exists('Swoole\Coroutine\Http\Client')决定HttpClient是否可用 -
Swoole\Coroutine::getCid()在非协程环境（比如onWorkerStart回调里）返回0是正常行为，不是 bug —— 4.8.10+ 和 5.x 统一了这个语义
PHP CLI 和 FPM 的 swoole.so 必须同时启用
Hyperf 启动走的是 CLI 模式，但很多部署场景下会混用 FPM（比如健康检查接口）。如果只在 /etc/php/8.3/cli/conf.d/ 启用了 swoole.so，而 /etc/php/8.3/fpm/conf.d/ 没配，定时任务或某些异步回调可能因环境切换导致协程上下文丢失。务必两边都检查并补全：extension=swoole.so。
版本兼容性不是“装上就行”的事，php --ri swoole 输出的每一行都对应一个潜在崩点；尤其注意 log_level 默认值从 5 变成 2、tcp_nodelay 默认关闭这些静默变更，它们不会报错，但会让服务在高并发下表现异常。
