WebSocket长连接心跳中断本质是“假在线”：连接看似正常但消息静默丢失，需同步排查客户端（心跳是否发出）、服务端（是否接收响应）、中间链路（Nginx超时/头透传/负载均衡）及状态一致性（僵尸连接泄漏）。
WebSocket长连接心跳中断不是“连不上”，而是“连着却收不到消息”——故障往往静默发生，日志无报错，用户无感知，直到业务数据开始丢失。排查要从客户端、服务端、中间链路三个层面同步切入，重点验证“心跳是否发出、是否送达、是否被响应、是否被识别”。
一、确认心跳是否真正发出（客户端侧）
很多问题其实卡在第一步：心跳压根没发出去。
- 检查前端定时器是否正确启动，比如
setInterval(() => ws.send(JSON.stringify({ type: 'ping' })), 30000)是否在onopen后才注册，避免连接未就绪就发包 - 打开浏览器 Network → WS → Frames 标签页，手动触发一次心跳后观察是否有 Text 类型的 ping 消息发出，注意时间戳和内容是否符合预期
- 若使用 WebSocket 原生 API，确认没有误将心跳消息发成二进制帧（
ws.send(arrayBuffer)），服务端可能直接忽略 - 检查页面是否进入后台或休眠状态（如 Chrome 标签页非激活、iOS Safari 进入省电模式），此时
setInterval可能被节流甚至暂停
二、验证心跳是否抵达服务端并被处理（服务端侧）
即使客户端发了，服务端也可能没收到、没解析、没响应。
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 在服务端接收逻辑中加日志，例如 FastAPI 的
websocket.receive_text()前后打点，确认 ping 消息是否进入处理流程 - 区分协议层 Ping/Pong 和业务层心跳：如果用的是
websocket.ping()（FastAPI/Starlette 内置），需确保服务端启用了自动 Pong 响应（默认开启），但部分自定义封装可能禁用了它 - 检查心跳消息格式是否与服务端校验逻辑匹配，比如要求
{"type":"ping","ts":1726428600}，而前端只发了"ping"字符串，导致 JSON 解析失败后被跳过 - 查看服务端连接状态管理：是否把超时未心跳的连接标记为“待清理”，但清理逻辑因锁竞争或异常被跳过？可临时打印所有活跃连接的最后心跳时间戳做横向比对
三、揪出中间链路上的“静默截断”（Nginx/负载均衡/防火墙）
这是最易被忽略、也最常导致“连接突然失活”的环节。
- 检查 Nginx 配置中
proxy_read_timeout是否足够长（推荐 ≥ 300 秒），默认 60 秒会直接切断空闲连接；同时确认proxy_send_timeout不小于心跳间隔 - 确认 Nginx 已透传关键升级头：
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade";缺一不可 - 云厂商负载均衡（如阿里云 SLB、AWS ALB）通常有独立的空闲超时设置（常为 60–300 秒），需登录控制台单独调整，不能只改 Nginx
- 企业内网防火墙或运营商 NAT 设备可能对长连接更激进，可通过抓包验证：在服务端执行
tcpdump -i any port 8000 -w ws.pcap，复现断连前后是否有 FIN/RST 包出现；若全程只有 SYN 和后续数据包、却突然无任何关闭信号，则大概率是中间设备单方面回收
四、定位“假在线”与资源泄漏（状态不一致）
客户端已断开，服务端还认为连接有效，这种状态错位会导致心跳检测完全失效。
- 检查服务端是否监听了
websocket.close()或websocket.exception事件，并及时从连接池中移除对应 session；未清理的“僵尸连接”会持续占用内存和句柄，最终拖垮整个服务 - 对比客户端
ws.readyState和服务端存储的连接状态：若前端显示CLOSED(3)，但服务端仍标记为OPEN，说明服务端未收到关闭帧或未处理异常退出 - 在服务端增加心跳响应超时机制：比如客户端发 ping 后 5 秒内未收到 pong，主动调用
close(4001, "heartbeat timeout")；这样可避免单向断连长期滞留 - 用
lsof -i :8000 | wc -l定期统计连接数，若持续增长且不回落，基本可判定存在连接泄漏
