hyperf 3.1 协程客户端复用失败、连接泄漏、响应延迟陡增的根本原因是连接未按协程生命周期管理；需检查容器绑定是否为 singleton、验证对象 id 是否一致、正确配置连接池（max_idle_time ≤ 60）、执行 try-finally 闭环释放连接，并用 lsof 排查泄漏。
Hyperf 3.1 中协程客户端复用失败、连接泄漏、响应延迟陡增，根本原因不是并发量高，而是连接未按协程生命周期正确管理——每个请求新建 Client 实例、忘记归还、混用同步扩展、空闲连接未清理都会直接击穿连接池防线。
确认协程客户端是否真正复用
打开 Hyperf 的 config/autoload/dependencies.php，检查是否将客户端类绑定为 Singleton 或 Container::SINGLETON；若绑定为 Container::FACTORY 或未显式声明，则每次 make() 都会 new 新实例，协程间无法共享连接。
在任意 Controller 方法中插入调试代码：var_dump(spl_object_id($this->httpClient));，发起两次连续请求，观察输出的 ID 是否一致；不一致说明未复用，需立即修正容器绑定方式。
这一步操作起来很简单，直接把文件拖进去就行。
HTTP 客户端连接池初始化与配置
方法一：使用官方 hyperf/http-client 内置池（推荐）
确保已安装：composer require hyperf/http-client；然后在 config/autoload/http-client.php 中配置：
'pool' => ['min_connections' => 5, 'max_connections' => 30, 'connect_timeout' => 5.0, 'wait_timeout' => 3.0, 'heartbeat' => ['interval' => 30], 'max_idle_time' => 60,]
【max_idle_time 必须设为 ≤ 60】，否则空闲连接长期滞留，可能被 SLB 或 NAT 网关静默断开，后续复用时触发重连+超时，造成 P99 延迟毛刺。
方法二：手动封装协程池（适用于自定义 Client）
新建 app/Pool/CustomHttpClientPool.php，继承 Swoole\Coroutine\Pool，重写 create() 方法返回 new \Hyperf\HttpClient\Client(['base_uri' => 'https://api.example.com'])；在 OnWorkerStart 回调中初始化该池并挂载到 Container。
注意：不要在 __construct 或 @Value 注入时初始化池——协程逃逸会导致 Worker 进程内多个副本。
安全释放连接的三步闭环
第一步：所有 HTTP 调用必须包裹在 try 块中；
第二步：在 finally 块中显式调用 $client->close()（若使用官方 Client）或 $pool->put($client)（若使用自定义池）；
第三步：禁止在协程结束前依赖 __destruct 自动关闭——GC 触发时机不可控，连接大概率泄漏；defer 可作补充但不可替代 finally。
这三步缺一不可。漏掉 finally 就等于放任连接在池外游荡；而仅靠 defer 在协程 panic 时不会执行，照样丢连接。
排查连接泄漏的现场命令
登录运行中的 Hyperf Worker 进程所在服务器，执行：lsof -p $(pgrep -f "hyperf:server") | grep ":443" | wc -l；持续观察该数值是否随请求量线性增长。
若数值突破 pool.max_connections × worker_num 总和，且稳定不下落，基本可判定存在连接未归还；此时立刻检查所有 HttpClient::post() 调用点是否遗漏 finally 块。
别信日志里“请求成功”的假象——连接泄漏不会报错，只会在高并发下突然卡死。
