Hyperf MySQL连接保活需启用heartbeat（建议30秒）与max_idle_time（建议60秒）双机制协同，确保连接池主动探测并清理失效连接，避免“MySQL server has gone away”错误；参数须在databases.php中正确配置，且不可混淆wait_timeout（连接获取超时，应保持3.0）。
Hyperf 设置 MySQL 连接保活，核心是让连接池主动探测并清理失效连接，避免出现 Connection has been closed 或 MySQL server has gone away 错误。这不是靠“延长超时”解决的，而是靠心跳检测（heartbeat）+ 空闲控制（max_idle_time）双机制协同工作。
开启并配置 heartbeat
heartbeat 是连接池定期向 MySQL 发送 PING 命令，验证连接是否仍然活跃。必须启用，且值要合理：
- 设为 30（单位：秒），即每 30 秒检查一次连接有效性
- 不能设为
-1（禁用），否则连接池无法感知连接是否已被 MySQL 主动断开 - 不能设得太小（如 5 秒），会增加数据库无谓压力；也不能太大（如超过 wait_timeout 的 1/2），起不到保活作用
- MySQL 默认
wait_timeout = 28800（8 小时），30 秒远小于它，足够安全
设置合理的 max_idle_time
这是连接在池中空闲多久后自动关闭的时间上限，和 heartbeat 配合形成双重保障：
MySQL8 CRM Schema Design Expert
下载
面向 CRM 系统的 MySQL 8 数据库模式设计。当用户需要为客户关系管理（CRM）系统设计、评审、优化或生成数据库模式时，应使用此项技能。
- 推荐设为 60.0（单位：秒），即空闲超 60 秒就释放连接
- 该值必须 ≤ MySQL 的
wait_timeout，否则连接可能在池中“存活”，但到 MySQL 侧已被强制关闭 - 开发或测试环境若 MySQL 的
wait_timeout被调得很低（比如 60），那这里也要同步下调，但不建议动服务端参数
确认连接池配置位置正确
所有参数都在 config/autoload/databases.php 的对应数据库配置中修改，例如：
（关键字段已加粗）
'pool' => [<br> 'min_connections' => 5,<br> 'max_connections' => 32,<br> 'connect_timeout' => 10.0,<br> 'wait_timeout' => 3.0,<br> <strong>'heartbeat' => 30,</strong><br> <strong>'max_idle_time' => 60.0</strong><br>],
避免常见误区
- 不要把
wait_timeout（连接池内等待连接的超时）误当成数据库空闲超时——它建议保持 3.0，不是 0.1 - 不要依赖降低 MySQL 的
wait_timeout来“解决断连”，这是反模式，反而加剧问题 - 冷启动时
min_connections至少设为 5～10，防止初始连接全部失效后池子变空 - 长周期任务（如导出、批量处理）应绕过连接池，用
DB::connection()->getPdo()拿直连，避免连接被中途回收
