Redis连接池wait_timeout超时表现为协程卡在get()并抛WaitTimeoutException，根本原因是并发超max_connections或pipeline/transaction未释放连接，以及MySQL异常污染Redis上下文等连锁问题。
Redis 连接池 wait_timeout 触发超时的典型表现
协程卡在 $redis->get('key') 上不动，几秒后抛出 Hyperf\Pool\Exception\WaitTimeoutException，日志里反复出现 “wait timeout” —— 这不是 Redis 慢，是连接池没空闲连接可分配。
根本原因是并发请求数超过了 pool.max_connections，而新协程又等不到连接释放。常见于：突发流量、事务/管道未及时结束、异常未触发连接归还。
- 检查
config/autoload/redis.php中pool.max_connections是否低于实际峰值 QPS × 平均耗时（例如 100 QPS × 0.1s = 10 连接，但建议留 2–3 倍余量，设为 30–50） -
pool.wait_timeout别设太小（如 0.1），否则协程还没等上就直接失败；也不宜过大（如 10s），会掩盖真实瓶颈；推荐 2.0–5.0 - 用
swoole_get_local_socket_count()或ss -s | grep ESTAB观察连接数是否长期贴近max_connections
pipeline/transaction 后连接不释放的泄漏点
调用 $redis->pipeline() 或 $redis->multi() 后，若中间抛异常、或忘记 ->exec()，连接会一直被该协程独占，直到协程退出——但协程可能长时间存活（比如在定时任务或长连接中），导致连接池“假性耗尽”。
Hyperf 的 Redis 客户端在 pipeline 内部使用协程上下文绑定连接，finally 块里才调 releaseContextConnection()。一旦 exec() 前异常跳出，这个清理逻辑就跳过了。
- 错误写法：
try { $redis->pipeline(...); throw new Exception(); } catch (...) { }→ 连接泄漏 - 正确写法：确保
pipeline和multi调用包裹在try/finally中，或改用withPipeline()等封装好的安全方法（Hyperf 3.1+ 提供） - 临时验证：在复现场景中加日志，打印
Context::has($redis->getContextKey())，为 true 但没exec就基本确认泄漏
MySQL gone away 后 Redis 连接也跟着断的连锁反应
不是 Redis 本身问题，而是业务代码里混用了 DB 和 Redis，在 MySQL 连接因 wait_timeout 断开后，事务回滚失败、异常未捕获，导致后续 Redis 操作在同一个协程里继续执行——此时协程上下文可能已损坏，Redis 客户端底层 Co\Redis 报 Connection reset by peer 或直接无响应。
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
这种“跨组件污染”在协程里特别隐蔽，因为错误源头和表现位置分离。
- 重点检查：是否在同一个协程内先操作 DB（尤其带事务），再操作 Redis；是否对
PDOException/QueryException做了兜底重试，但没清理 Redis 上下文 - 简单隔离手段：用
Coroutine::create()显式切协程，让 DB 和 Redis 操作不在同一上下文 - 更稳妥做法：在 DB 异常处理块末尾，手动调
$redis->close()（如果确定当前用了独立实例）或清空 Context：Context::set($redis->getContextKey(), null)
connect_timeout=0 导致协程永久挂起
把 pool.connect_timeout 设成 0，本意是“不限时”，结果是协程永远卡在 DNS 解析或 TCP 握手阶段，既不失败也不继续——Swoole 底层不会触发超时回调，整个协程就“静默死亡”了。
这比报错更难排查，因为没有日志、没有堆栈、只表现为接口无响应。
-
connect_timeout必须是正浮点数，生产环境建议 2.0–5.0；0 和 null 都等效于“无限等待” - DNS 不稳时，
connect_timeout实际包含 DNS 查询时间；若用域名连 Redis，务必搭配异步 DNS（swoole_async_dns_lookup=1）或直连 IP - 验证方式：在出问题的机器上跑
time dig your-redis-host.com +short，若超过 2 秒，就要怀疑 DNS 是瓶颈
协程环境里，“连接”不是资源句柄，而是上下文状态。一个 wait_timeout 错误背后，可能是 pipeline 没 exec、可能是 DB 异常污染了 Redis 上下文、也可能是 DNS 卡住整个协程——得一层层剥开看，不能只盯着 Redis 配置改。
