hyperf 必须依赖正确启用并配置的 swoole 扩展才能运行，需确保 php ≥ 8.0、swoole ≥ 4.8，通过 php --ri swoole 验证启用状态，禁用 disable_functions 中的关键函数，并在 .env 中设置 swoole_hook_flags=swoole_hook_all。
Hyperf 必须依赖 Swoole 扩展才能运行，但仅安装 Swoole 并不等于能用——关键在“启用+配置正确”。很多启动失败（比如 Class 'Swoole\Http\Server' not found）都是因为扩展没真正加载，或被 PHP 配置拦住了。
确认 PHP 版本与 Swoole 兼容性
Hyperf 3.x 要求 PHP ≥ 8.0，Swoole ≥ 4.8（推荐 4.10+）。不匹配会导致编译失败或运行时异常：
- 运行
php -v查版本，低于 8.0 需先升级 PHP - 查 Swoole 官方发布页或 GitHub Releases，选对应 PHP 版本的 Swoole 包（如 PHP 8.1 用 swoole-4.10.1）
- 避免混用：用
pecl install swoole时，确保当前 CLI 的 php-config 与 Web SAPI 一致
安装并启用 Swoole 扩展
推荐两种方式，按环境选择：
-
宝塔/面板用户：直接进 PHP 设置 → 扩展管理 → 勾选 Swoole → 关闭 “Short Name”（即设
swoole.use_shortname = Off）→ 重启 PHP -
命令行用户：
- 进入 Swoole 源码目录，执行：
phpize./configure --with-php-config=/path/to/php-config（用which php-config确认路径）make && make install - 编辑
php.ini，追加两行：extension=swoole.soswoole.use_shortname = Off - 重启 PHP-FPM 或 Web 服务
- 进入 Swoole 源码目录，执行：
验证是否真正生效
光看 php -m | grep swoole 不够，必须检查运行时状态：
- 执行
php --ri swoole，确认输出中support async_redis => enabled、http2 => enabled等关键项为enabled - 检查
disable_functions是否禁用了pcntl_fork、exec、shell_exec等——Swoole 启动进程模型依赖这些函数，必须从该项中移除 - 运行
php -r "new Swoole\Http\Server('0.0.0.0', 9501);"，无报错即基础可用
配合 Hyperf 的必要设置
Swoole 装好了，Hyperf 还可能因配置卡住：
- 项目根目录
.env中建议显式添加：SWOOLE_HOOK_FLAGS=SWOOLE_HOOK_ALL（尤其涉及协程 MySQL/Redis 时） - 若用 Docker，需确保容器内
/proc/sys/net/core/somaxconn ≥ 511，否则 Swoole 启动报错 - 开发时可临时加
php bin/hyperf.php start --watch，快速验证改动是否触发热重载
