Hyperf连接池wait_timeout控制获取连接的最大等待时长，超时抛ConnectionWaitTimeoutException；它非网络或SQL超时，而是协程在池中排队等待空闲连接的上限，需结合max_connections、业务并发与响应时间协同调整，推荐默认3.0秒，延迟敏感场景设0.5~1.0秒，后台任务可设5.0~10.0秒，并优先排查连接泄漏而非盲目调大。
Hyperf 中连接池等待连接超时时间主要由 wait_timeout 配置控制，它决定当连接池中无可用连接时，请求最多等待多久；超时后会抛出 ConnectionWaitTimeoutException。优化该参数需结合业务并发模型、下游响应时间和连接池容量综合调整，而非单纯调大或调小。
理解 wait_timeout 的实际作用
wait_timeout 不是网络连接超时，也不是 SQL 执行超时，而是「从连接池获取连接」这个动作的阻塞等待上限。例如：
- 连接池最大连接数（
max_connections）设为 10，当前已有 10 个请求正在使用连接； - 第 11 个请求进来，就会进入等待队列；
- 若等待超过
wait_timeout（如 3 秒），则直接失败，不继续等。
合理设置 wait_timeout 的建议值
默认值通常为 3.0（秒），但应根据以下情况调整：
- 对延迟敏感的服务（如网关、实时接口），建议设为
0.5 ~ 1.0，快速失败，避免线程堆积； - 批处理或后台任务可适当放宽至
5.0 ~ 10.0，容忍短时连接紧张； - 若频繁报
ConnectionWaitTimeoutException，优先检查是否max_connections过小或存在连接泄漏，而不是盲目加大wait_timeout。
配合调整的关键配置项
wait_timeout 需与其它连接池参数协同优化：
- max_connections：确保其 ≥ 并发峰值 × 平均单次请求持有连接时长（秒）/ 平均响应时间（秒），粗略估算可先设为 QPS × 99% 响应时间 × 1.5；
-
min_connections：设为
max_connections的 30%~50%，减少冷启动连接创建开销； -
connect_timeout 和 recv_timeout：单独控制底层 TCP/协议交互超时，与
wait_timeout无关，但共同影响整体稳定性。
验证与监控方法
上线后需通过日志和指标确认效果：
- 开启连接池 debug 日志：
"hyperf/connection-pool": "debug"，观察Wait timeout报错频率； - 监控
connection_pool.waiting_num和connection_pool.idle_num（通过 Prometheus + Hyperf Metrics）； - 压测时逐步提高并发，观察
wait_timeout触发率突增点，反推连接池瓶颈。
