Hyperf MySQL连接池报WaitTimeoutException或“wait timeout”错误，本质是协程排队超时，非连接池故障；需调大pool.wait_timeout（推荐3.0～5.0）、合理设置max_connections（按QPS×耗时反推），并严格使max_idle_time < MySQL wait_timeout、heartbeat ≤ max_idle_time/2，启用IdleConnectionChecker主动剔除死连接。
Hyperf MySQL 连接池 wait_timeout 报错不是连接池问题
报 WaitTimeoutException 或日志里反复出现 “wait timeout”，不代表连接池坏了，而是协程在池里排队等连接，等不到就直接失败。这说明 pool.wait_timeout 设置过小，或者 pool.max_connections 真的不够用了。
常见错误现象：
- 高并发下大量请求瞬间失败，错误堆栈含
Hyperf\Pool\Exception\WaitTimeoutException - 数据库 ESTABLISHED 连接数长期卡在
pool.max_connections附近（用ss -s | grep ESTAB或swoole_get_local_socket_count()验证） - 调大
wait_timeout后错误减少，但响应变慢、堆积更明显
实操建议：
-
pool.wait_timeout推荐设为3.0～5.0，别用默认0.1—— 太小会让抖动被误判为故障；也别设 >8.0，否则掩盖真实瓶颈 - 先确认是否真缺连接：
SHOW STATUS LIKE 'Threads_connected';对比pool.max_connections，若接近或持平，说明池子确实满了 - 检查是否有连接泄漏：比如
$db->transaction()中未提交/回滚、pipeline()调用后没exec()、或异常跳出导致连接未归还
max_connections 算不准？从 QPS × 耗时反推
pool.max_connections 不是拍脑袋定的数字，它必须反映「同时活跃连接数」的峰值需求。凭感觉设成 100 或 200，反而容易压垮 MySQL。
使用场景：
- 普通接口：峰值 QPS × 平均 DB 操作耗时（秒）
- 带 pipeline/multi 的 Redis 或批量 SQL：按「pipeline 命令数 × 并发协程数」估算
- 定时任务 / WebSocket 长连接：这些常驻协程会独占连接，必须单独计入余量
参数差异与影响：
- MySQL 默认
max_connections=151，Hyperf 的pool.max_connections建议 ≤100（留 30% 给备份、监控、DBA 临时登录） - 设太高会导致 MySQL 报
Too many connections；设太低则大量协程排队失败 - 线上应配合
pool.min_connections ≥ 5，避免冷启时所有协程抢唯一连接，一旦该连接失效，全链路卡死
Connection has been closed 的真实原因和心跳配置
这个错误不是网络断了，而是连接池归还连接时发现它已被 MySQL 主动关闭（比如触发了 wait_timeout），然后试图复用时直接崩掉。根本解法不是调小 wait_timeout，而是让连接池提前感知并剔除死连接。
关键点：
-
heartbeat必须启用且设合理值（如30），否则连接池无法主动探测连接有效性 -
max_idle_time必须 严格小于 MySQL 的wait_timeout（查法：SHOW VARIABLES LIKE 'wait_timeout';），推荐设为wait_timeout - 30 -
heartbeat应 ≤max_idle_time，推荐max_idle_time / 2（例如max_idle_time=270，则heartbeat=135） - 驱动不支持
PING（如某些 PostgreSQL Proxy）时，可改用'checker' => 'SELECT 1'，但注意该语句不能在事务中执行
为什么开了 heartbeat 还报 “MySQL server has gone away”
因为 Hyperf 的 heartbeat 默认只在连接被取出时单次 PING，不是后台常驻检测。真正起作用的是 IdleConnectionChecker 线程，它依赖 max_idle_time 和 heartbeat 协同工作。
容易踩的坑：
-
max_idle_time > wait_timeout：连接在池里“睡过头”，取出来必失效 -
heartbeat设太小（如5）：每秒高频PING，压垮数据库；设太大（如300）：等于没检测 -
min_connections = 0：冷启延迟高，且第一个请求失败概率陡增 - MySQL 的
wait_timeout和 Hyperf 的pool.wait_timeout完全是两回事，混用会导致配置逻辑混乱
复杂点在于：这些参数不是孤立生效的，min_connections、max_idle_time、heartbeat、MySQL 侧 wait_timeout 必须形成闭环，漏掉任意一环，都可能让连接池在“看似正常”的状态下持续产出 Connection has been closed 或 server has gone away 错误。
