HyperfWebSocket断连问题及Nginx优化方案

Hyperf WebSocket频繁断连往往并非框架本身问题，而是Nginx代理超时设置与Swoole心跳机制不匹配所致：Nginx默认60秒的proxy_read_timeout极易在心跳间隔（如45秒）后主动中断空闲连接，导致客户端报错1001或ConnectionClosedError；解决关键在于将Nginx的proxy_read_timeout和proxy_send_timeout同步设为至少90秒（推荐86400），并确保启用HTTP/1.1升级头，同时严格配置Swoole的heartbeat_check_interval（如25）与heartbeat_idle_time（如60），二者差值不小于20秒以容忍网络抖动；还需注意Hyperf不自动响应自定义ping帧，前端须使用原生WebSocket或服务端手动实现pong解析，而客户端重连必须配合服务端onClose的及时资源清理与旧连接驱逐，才能真正实现高可用、低泄漏的长连接稳定运行。

Hyperf WebSocket连接断开，先看Nginx的proxy_read_timeout是否匹配心跳间隔

Hyperf本身不会无缘无故断连，但Nginx默认proxy_read_timeout=60s会主动掐掉空闲连接。如果你的心跳设成每45秒发一次，而Nginx在第61秒没收到任何数据就关闭后端连接，客户端就会看到code=1001或直接ConnectionClosedError。

必须让Nginx的超时值 > 心跳间隔 + 服务端处理缓冲时间。生产环境建议：

• proxy_read_timeout设为86400（24小时），或至少90（比心跳间隔大15秒以上）
• proxy_send_timeout同步设为相同值，避免发心跳帧时被截断
• 确认proxy_http_version 1.1和proxy_set_header Upgrade $http_upgrade已启用，否则握手阶段就失败

Hyperf服务端heartbeat_check_interval和heartbeat_idle_time不能随便填

Swoole底层靠这两个参数判断连接是否“活”。设错会导致连接被误杀——比如heartbeat_check_interval=30但heartbeat_idle_time=40，意味着最多只允许10秒误差，弱网下极易触发强制踢出。

推荐组合（基于Hyperf 3.x + Swoole 5.x）：

• heartbeat_check_interval => 25：每25秒检查一次客户端有没有响应
• heartbeat_idle_time => 60：允许连接空闲最长60秒，留出足够缓冲应对网络抖动
• 二者差值必须 ≥ 20秒，否则心跳响应延迟稍高就会被判定为失效

注意：这些是Swoole Server配置项，不是Hyperf WebSocket Handler里的逻辑；改完要重启服务，热更新不生效。

客户端没回pong，Hyperf服务端不会自动重试，只会静默关闭

Hyperf/Swoole的WebSocket服务器默认不自动响应ping帧——它只负责检测“你有没有发pong回来”，不帮你发pong。如果前端用原生WebSocket对象但没注册onmessage监听ping帧，或者服务端发的是自定义JSON心跳（如{"type":"ping"}），那Swoole根本收不到标准PONG帧，heartbeat_idle_time一到就关连接。

解决方式只有两个：

• 前端用标准WebSocket API，并确保浏览器支持自动响应ping（Chrome/Firefox/Edge均支持，无需手动写onmessage处理）
• 若必须用自定义心跳格式，就得在Hyperf里自己实现onMessage逻辑解析{"type":"pong"}并更新连接活跃时间戳，不能依赖Swoole内置心跳

重连逻辑写在客户端，但别让Hyperf服务端堆积无效连接

客户端反复重连时，Hyperf服务端若没及时清理旧连接，会快速耗尽max_connection或触发Swoole的FD泄漏。关键点在于：onClose回调里必须显式释放资源，且不能漏掉close后的清理步骤。

常见疏漏：

• 没调$fd对应的$server->exist($fd)校验连接是否还存活，就直接操作上下文
• 在onClose里异步执行清理（如Redis删除用户状态），但没用go协程包裹，导致阻塞事件循环
• 重连时客户端带了新token，但服务端没在onOpen里校验并踢掉旧连接，造成一人多连

真正稳的重连，是客户端节制（指数退避+最大重试次数），服务端干净（每次onClose都做unset、del、close三连）。中间任意一环松动，连接数曲线就会像心电图一样上蹿下跳。

以上就是《HyperfWebSocket断连问题及Nginx优化方案》的详细内容，更多关于的资料请关注golang学习网公众号！