ThinkPHP连接池等待超时需配置pool.wait_timeout（秒），但必须安装think-pool扩展并正确注册，否则配置无效；超时抛WaitTimeoutException，需业务层捕获降级。
ThinkPHP 连接池等待超时怎么配
ThinkPHP 本身不内置数据库连接池，所谓“连接池等待超时”其实是底层 PDO 连接复用 + 连接管理器的排队逻辑，由 think\db\Connection 和连接池中间件（如 think-pool 扩展）共同作用。默认没有熔断，必须手动干预排队行为。
核心控制点在数据库配置的 pool 项和 wait_timeout 参数：
-
wait_timeout是连接池等待空闲连接的最大秒数，超时抛出think\exception\PDOException，不是 MySQL 的wait_timeout变量 - 必须启用连接池：配置中设
'pool' => ['max_active' => 10, 'wait_timeout' => 3] - 若没装
think-pool扩展，pool配置会被忽略，wait_timeout不生效
为什么加了 wait_timeout 还不报错直接卡住
常见于没启用真正的连接池实现，或协程环境未适配。ThinkPHP 6.0+ 默认使用同步阻塞 I/O，即使配了 wait_timeout，底层仍可能卡在 PDO::__construct 或连接初始化阶段，而非池内排队环节。
排查要点：
立即学习“PHP免费学习笔记（深入）”；
- 确认已安装并注册
think-pool：运行composer require topthink/think-pool，并在app/provider.php中添加think\pool\Provider::class - 检查
config/database.php中pool配置是否在正确位置（应位于具体数据库配置下，如mysql.pool） - 同步模式下，
wait_timeout仅对「从池中取连接」有效；若连接创建失败（如网络不通），会绕过池逻辑直接抛错或卡死
如何让排队太久直接返回错误而不是让用户干等
不能只靠配置，得在业务层捕获并降级。ThinkPHP 的连接获取异常是 think\exception\PDOException，但池等待超时抛的是 think\pool\WaitTimeoutException（来自 think-pool）。
实操建议：
- 在关键查询前加
try...catch，捕获think\pool\WaitTimeoutException，快速返回友好的提示或兜底数据 - 避免在控制器里裸写
Db::table()->select()，封装成服务方法，统一处理池异常 - 配合
max_wait_time（毫秒级）更精细控制：例如'wait_timeout' => 2.5表示 2.5 秒，但部分版本只接受整数秒，建议用max_wait_time替代
示例片段：
try {
return Db::table('user')->where('id', 1)->find();
} catch (\think\pool\WaitTimeoutException $e) {
// 记录日志，返回 HTTP 503 或空数据
Log::error('DB pool timeout: ' . $e->getMessage());
return json(['code' => 503, 'msg' => '服务繁忙，请稍后再试']);
}
并发高时熔断容易失效的几个坑
ThinkPHP 的池熔断依赖单进程内的连接对象复用，一旦启用了 FPM 多 worker 或 Swoole 多协程，每个进程/协程有独立池实例，全局并发阈值实际是 worker_num × max_active，很容易误判。
典型陷阱：
- FPM 场景下，
max_active设为 10，但开了 20 个 php-fpm 子进程 → 实际最大连接数是 200，远超 MySQL 的max_connections，导致 MySQL 主动拒绝新连接，此时抛的是PDOException而非池超时 - Swoole 下未调用
Pool::destroy()或未设置release_on_close，连接不归还，池迅速耗尽 - 事务未正常结束（没
commit或rollback），连接被长期占用，wait_timeout对它无效
最稳妥的做法是：MySQL 层设 wait_timeout=10（秒），应用层池设 wait_timeout=3，再加监控看 show status like 'Threads_connected'，三者联动才不容易漏掉长连接或雪崩点。
