Hyperf协程启动失败90%因三问题：PHP版本＜8.1、Swoole未启用协程、注解扫描未生效；协程中禁用sleep等同步函数，须用co::sleep和HttpClient；数据须用Context隔离，避免全局变量污染。
Hyperf 协程不是“装完就能跑”，新手卡住的绝大多数问题，都集中在三个地方：PHP 版本或 Swoole 扩展没对齐、注解扫描链断裂、协程里误用同步阻塞调用。只要这三关过了，后续开发才真正进入可控状态。
启动直接 Segmentation fault 或静默无输出？先查这三项硬性依赖
这不是代码写错了，而是底层环境根本没准备好。Hyperf 启动失败 90% 都卡在这三点上，必须逐项确认：
-
php -v输出必须 ≥ 8.1；低于该版本，协程支持被跳过，co::sleep()、go()等函数会直接失效或崩溃 -
php --ri swoole输出中必须包含support coroutines: enabled；如果没看到，说明加载的是旧版 Swoole（比如系统自带的 4.x），需检查php.ini中extension=swoole.so指向的是否为 5.0+ 协程版 - 首次运行
php bin/hyperf.php start前，必须执行composer install --no-dev（生产）或至少composer dump-autoload（开发）；否则注解扫描器无法加载控制器类，@AutoController形同虚设，服务看似启动成功，实则路由全挂
@AutoController 注解路由不生效？重点检查 annotations.php 和缓存开关
访问 /api/index 返回 404，但 config/routes.php 里手写的路由能通——这是典型的注解扫描链中断。不是框架坏了，是配置漏了：
-
config/autoload/annotations.php中的'paths'必须显式列出控制器目录，例如['app/Controller']；只写['app']不行，Hyperf 默认不递归扫描子目录 - 开发时务必把
'cacheable' => false设为false；一旦开启注解缓存，改了@GetMapping不重启服务就完全无效，极易误判为“代码没生效” -
#[AutoController]所在类必须严格符合 PSR-4：文件名IndexController.php对应命名空间App\Controller\IndexController；大小写错一个字母、多一个空格，都会导致类加载失败
协程里用了 sleep()、file_get_contents() 就卡死？替换方案必须记牢
这些函数在传统 PHP-FPM 下没问题，但在 Hyperf 协程中等于“给整个 worker 进程下毒”：它们会阻塞当前线程，导致调度器无法切换其他协程，并发能力归零，甚至服务假死。
- 替代
sleep(1)：必须用co::sleep(1)（注意是co::sleep，不是Coroutine::sleep） - 替代
file_get_contents($url)：必须用Hyperf\HttpClient\Client实例的get()方法，不能直接调原生函数 - 数据库操作必须走
Hyperf\Database\Connection或 Eloquent ORM；直接调PDO原生方法会复用连接句柄，很快触发MySQL server has gone away - 事务必须用
DB::transaction()包裹；手动beginTransaction()+commit()极易跨协程污染连接状态
协程间数据串流、日志混乱？上下文隔离不是可选项
高并发下出现“张三看到李四的订单”、异步任务里拿不到请求 ID、父子协程传参失败——这些问题根源都是用了全局变量或静态变量共享数据。协程不是线程，没有内存隔离，必须靠上下文机制。
- 不要用
global $user_id或static $token存请求数据；每个协程需要自己的“数据容器” - 获取当前协程上下文：用
Hyperf\Context\Context::get('request_id')；设置用Context::set('user_id', 123) - 父协程创建子协程时，上下文默认继承；但若子协程内调用
go()或co()新启协程，需手动传递关键值，否则丢失 - 日志打印务必带上
co::id()和Context::get('request_id')，否则多协程日志混在一起，排查等于大海捞针
协程真正的复杂点不在语法，而在心智模型转换：它要求你时刻意识到“当前代码运行在哪一个协程里”“这个变量属于谁”“这次 IO 是否会让出控制权”。很多坑不是不会写，而是没意识到自己正站在悬崖边上——而最常被忽略的，就是上下文隔离和注解缓存这两处“静默陷阱”。
