PHP Hyperf框架怎么用_PHP高性能协程框架Hyperf入门与实战【实战】-php教程-PHP中文网

hyperf启动失败主因是swoole扩展未正确安装、注解未扫描到、协程中使用阻塞写法；需检查php≥8.1、swoole启用协程、注解路径配置正确、关闭注解缓存，并避免exit/die及同步函数。

php hyperf框架怎么用_php高性能协程框架hyperf入门与实战【实战】

Hyperf 不是“装完就能跑”的传统 PHP 框架，启动失败、路由不生效、数据库查不出数据——这些问题基本都卡在三个地方：Swoole 扩展没装对、注解没扫描到、协程环境里用了阻塞写法。

看到 Segmentation fault、Class not found 或直接无输出，大概率是底层依赖没对齐：

php -v 必须 ≥ 8.1；低于版本会跳过协程支持，后续所有功能都不可靠
php --ri swoole 要显示 support coroutines: enabled，否则 extension=swoole.so 可能加载了旧版（比如系统自带的非协程版）
Windows 用户别硬扛本地编译，docker-compose up -d 直接拉起官方镜像更稳，避免 zlib、openssl 等扩展缺失引发的静默失败
启动前务必运行 composer install --no-dev（生产环境），否则 hyperf/di 容器可能因反射解析失败而崩溃

访问 /hello 返回 404，但 config/routes.php 里写死的路由能通——说明注解扫描链断了：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

确认 config/autoload/annotations.php 中 scan 配置包含你的控制器目录，例如：'paths' => ['app/Controller']
开发环境必须关掉注解缓存：'cacheable' => false，否则改了注解不重启服务就无效
#[Controller] 和 #[GetMapping] 必须在同一类中，且类文件名要匹配 PSR-4（如 HelloController.php 对应 App\Controller\HelloController）
别在控制器方法里用 exit 或 die，它会中断协程调度，导致后续请求卡住

协程环境下数据库操作不是“发请求→等结果”，而是“发请求→让出控制权→等回调”，所以错用同步写法必崩：

绝对不要在协程中调用 mysql_connect、file_get_contents 或 sleep()；要用 co::sleep()、Hyperf\HttpClient\Client、Hyperf\Database\Connection
事务必须用 DB::transaction() 包裹，手动 beginTransaction + commit 容易跨协程复用连接，引发 MySQL server has gone away
查不到数据？先看 config/autoload/database.php 的 pool.min_connections 是否为 0 —— 开发时设成 1，否则首次请求可能因连接池为空而超时
模型查询记得加 ->useWritePdo() 强制走写库，读写分离场景下 where()->first() 默认走读库，主从延迟会导致刚插入就查不到

注册了 UserRegistered 事件和监听器，但发事件后监听器完全没反应：

监听器类必须实现 Hyperf\Event\Contract\ListenerInterface，且在 config/autoload/listeners.php 中显式注册，不能只靠注解自动发现
事件对象本身必须是 PHP 类（不能是数组或字符串），且构造参数要可序列化；含闭包或资源句柄会直接静默失败
监听器执行耗时超过 swoole.server.settings.worker_max_request（默认 1000）会导致进程重启，事件中途丢失，建议监听器内只做轻量投递（如发消息队列）
测试时用 php bin/hyperf.php event:listen 命令验证监听器是否被正确加载，比盲猜快得多

最常被忽略的是：Hyperf 启动后所有代码都在常驻内存里运行，var_dump 和未捕获异常不会像 FPM 那样刷屏报错，而是写进 runtime/logs/hyperf.log。不看日志，等于闭眼调协程。