核心问题是swoole版本、加载方式、运行环境三者不匹配，需逐层验证：检查php --ri swoole确认coroutine enabled及version≥5.0；用find定位swoole.so并绝对路径写入php.ini；确保php≥8.1、opcache.enable_cli=0；用composer why-not等命令排除依赖冲突；最后用go()测试脚本验证协程可用性。
Linux 下搭建 Hyperf 时遇到 Swoole 冲突，核心问题不是“Swoole 装多了”，而是版本、加载方式、运行环境三者不匹配。常见表现包括：php bin/hyperf.php start 静默退出、Class not found、协程不可用、或启动时报 swoole 扩展未找到。解决关键在于逐层验证，而非重装。
确认 Swoole 是否真正加载成功
很多人执行 pecl install swoole 后以为就完了，但 PHP 实际没加载扩展：
- 运行
php --ri swoole，必须看到两行关键输出：
coroutine => enabled 和 Version => 5.x.x（Hyperf 3.x 要求 ≥5.0） - 若提示 “Extension 'swoole' not present”，说明扩展未加载；若显示 coroutine => disabled，说明协程被禁用，Hyperf 无法运行
- 查
swoole.so真实路径：find /usr -name "swoole.so" 2>/dev/null，常见位置如/usr/lib/php/20220829/swoole.so（PHP 8.2） - 在
php.ini末尾显式写入绝对路径：extension=/usr/lib/php/20220829/swoole.so，不要只写extension=swoole - 改完后重启 CLI 环境或运行
php -v验证，php -m | grep swoole应有输出
检查 PHP 与 Swoole 版本兼容性
Hyperf 对底层环境有硬性要求，错一个版本就可能失败：
- Hyperf 3.x 要求：PHP ≥ 8.1、Swoole ≥ 5.0（且必须启用协程）
- Ubuntu 默认源的 PHP 常为 8.1 以下，建议添加 Ondřej PPA：
sudo add-apt-repository ppa:ondrej/php && sudo apt update && sudo apt install php8.2 - 运行
php -v和php --ri swoole | grep -E "(Version|coroutine)"双重确认 - 特别注意：
opcache.enable_cli=0必须在php.ini中显式设为 0，否则 CLI 下 opcache 会破坏协程调度
排除 Composer 依赖层面的 Swoole 冲突
有时冲突不来自扩展本身，而来自不同包对 swoole 或其依赖（如 psr/http-message）的版本声明不一致：
- 运行
composer why-not swoole/extension:^5.0查谁在阻止你用正确版本 - 用
composer show --tree hyperf/framework看它实际拉了哪些组件及版本，避免混用 v2/v3 组件 - 若引入了非 Hyperf 官方包（如某些老版 SDK），检查其是否声明支持协程；重点看
connect()、stream_socket_client()等调用是否被协程 Runtime 拦截 - 临时清理干扰：
rm -rf vendor/ composer.lock，再composer install --no-dev，确保环境干净
验证协程是否真能工作
即使扩展加载、版本达标，协程仍可能因配置失效：
- 新建测试脚本
test_coro.php：<?php go(function () { echo "coro ok\n"; }); \Swoole\Coroutine::sleep(0.1); - 执行
php test_coro.php，有输出即协程可用；若报错或无输出，说明协程环境未就绪 - 检查是否误加了
ini_set('swoole.enable_coroutine', '0')—— Hyperf 全流程依赖协程，关闭即崩 - 用
strace -p $(pgrep -f "php bin/hyperf.php start") -e trace=epoll_wait观察是否进入事件循环，卡在epoll_wait且无返回，大概率是协程未启动或被阻塞
