根本原因是协程阻塞点未清理：同步I/O（如file_get_contents、curl_exec）、静态状态污染（如static单例、模型静态属性）、未释放资源（如pipeline未exec、Redis连接不归还）三类问题会直接卡死worker进程，导致QPS归零、日志无响应。
直接替换 Laravel 代码到 Hyperf 后出现接口卡死、QPS 归零、日志无响应？不是代码写错了，是协程阻塞点没清理干净。必须逐层排查同步 I/O、静态状态、未释放资源这三类硬性阻塞源。
哪些 Laravel 常用写法在 Hyperf 里会直接卡住协程
协程环境里，任何原生同步阻塞调用都会让整个 worker 进程挂起，不是慢，是停摆。以下写法在 Laravel 里安全，在 Hyperf 里是定时炸弹：
-
file_get_contents()、curl_exec()、sleep()—— 必须替换成Co::readFile()、$httpClient->get()、Co::sleep() -
DB::table()->where()->get()看似没问题，但若底层驱动未启用协程 Hook（如 mysqli 扩展未被 Swoole 劫持），仍会同步阻塞；确认方式：运行php --ri swoole，检查mysql => enabled -
ini_set('max_execution_time', 0)或set_time_limit(0)在常驻进程中失效，且掩盖真实阻塞点，应删掉 - 第三方包里隐式调用的
stream_socket_client()、fopen()—— 比如某些 SDK 的日志上报、配置拉取逻辑，需翻源码或用strace -p [pid] -e trace=connect,recvfrom抓系统调用
为什么 DB::transaction() 看起来在跑，实际却没生效
Laravel 的 DB::transaction() 依赖请求生命周期结束时自动回滚兜底，Hyperf 没这个机制。漏写 rollback 就等于数据脏写，且事务连接可能被其他协程复用导致错乱。
- 错误写法：
DB::beginTransaction(); ... DB::commit();—— 静态门面不绑定协程上下文，异常时不会自动 rollback - 正确写法：用
Connection::transaction()，它内部已做协程上下文绑定，异常时强制 rollback 并释放连接 - 注意：如果模型用了
static::$booted或protected $connection手动赋值，事务会跨协程污染；所有模型实例应声明为@Inject(transient=true) - 验证方式：在事务内故意 throw 异常，查数据库是否回滚；再并发两个事务请求，确认彼此隔离
Redis pipeline/multi 为什么执行完就卡住不返回
$redis->pipeline() 或 $redis->multi() 后未调用 ->exec()，连接会被独占直到协程退出——而协程可能长期存活（比如在 WebSocket 连接或定时任务中），导致连接池耗尽。
- 典型泄漏场景：
try { $redis->pipeline(); throw new Exception(); } catch (\Throwable $e) { }→finally块缺失，连接未释放 - 安全写法：必须包裹
try/finally，或改用 Hyperf 3.1+ 提供的withPipeline()封装方法 - 临时诊断：在 pipeline 调用前后加日志，打印
Context::has($redis->getContextKey())，若为true但没exec()，基本就是泄漏点 - 生产配置：检查
config/autoload/redis.php中pool.max_connections是否足够（建议设为峰值 QPS × 平均耗时 × 3），pool.wait_timeout设为2.0–5.0，避免过早失败或掩盖瓶颈
慢查询不是“慢”，是协程调度器被锁死
一条没索引的 SELECT * FROM users WHERE name LIKE '%xxx%'，会让当前协程无限等待 MySQL 返回，整个 worker 进程无法调度其他协程，QPS 归零。
- 现象：压测时
swoole_server->stats()显示coroutine_num持续飙升，request_count几乎不动；strace -p [pid] -e trace=recvfrom可见大量阻塞在recvfrom -
DB::timeout(5)对原始查询无效，必须在config/autoload/database.php中显式配置'options' => [PDO::ATTR_TIMEOUT => 5]，并确保 MySQL 驱动支持 - 关联查询
with(['profile'])若profile.user_id无索引，JOIN 会退化为全表扫描，比 N+1 更糟；用DB::enableQueryLog()+EXPLAIN FORMAT=TREE验证执行计划 - 别信 “开了 Swoole aio 就能救”，aio 不接管 MySQL 协议层；先加索引，再调优连接池和超时，最后才考虑 aio
协程阻塞点排查不是靠猜，而是靠 strace 抓系统调用、靠 DB::enableQueryLog() 看 SQL、靠 Context::has() 查连接归属——工具链用对了，80% 的卡死问题 10 分钟内定位。
