WebSocket连接超时需前后端协同控制，前端无法单靠“等待”实现，必须通过主动心跳、超时检测与指数退避重连来保障可靠性。
WebSocket连接超时不能靠前端“等”出来，必须前后端协同控制；前端唯一能做的，是感知断连并执行合理重连——否则只会卡在readyState === 0或反复创建无效连接。
为什么pingTimeout和pingInterval必须后端配
前端WebSocket对象本身没有内置心跳超时参数。所谓“连接超时”，实际是服务端在未收到客户端pong响应时主动关闭连接，这个判定完全由后端的pingTimeout（如 Socket.IO 默认 5000ms）和pingInterval（默认 25000ms）决定。前端即使调用ws.close()，也只影响本地状态，不改变服务端连接存活逻辑。
常见错误：
- 前端监听
onclose但没检查event.code，把服务端因ping timeout关闭当成正常退出 - 误以为设置
ws.timeout = 10000有效（该属性不存在） - 在
onerror里直接new WebSocket()，导致未关闭旧实例、缓冲区堆积、内存泄漏
前端重连必须带指数退避和最大次数限制
无节制重连会触发“重连风暴”，尤其在服务端短暂不可用时，所有客户端同步重试，瞬间压垮负载均衡器或后端连接池。
立即学习“前端免费学习笔记（深入）”；
实操要点：
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 初始延迟从
1000ms起步，每次失败翻倍，上限建议30000ms（30秒） - 必须设
maxReconnectAttempts（如5次），超过后停止并提示用户检查网络 - 每次重连前调用
ws?.close(4999, 'reconnect')，确保旧连接释放，避免readyState === 0残留 - 用
setTimeout而非setInterval，防止多次重连定时器叠加
示例关键逻辑：
let reconnectCount = 0;
const maxRetries = 5;
const baseDelay = 1000;
<p>function connect() {
ws = new WebSocket('wss://api.example.com');
ws.onopen = () => { reconnectCount = 0; };
ws.onclose = (e) => {
if (e.code === 4999 || e.code === 1006) {
if (reconnectCount < maxRetries) {
const delay = Math.min(baseDelay * (2 ** reconnectCount), 30000);
setTimeout(connect, delay);
reconnectCount++;
}
}
};
}
onerror不是重连入口，而是连接失败信号
onerror会在new WebSocket()阶段就触发（如 DNS 失败、SSL 握手异常），此时ws.readyState通常为0（CONNECTING）。它不表示已建立连接后断开，因此不能直接复用onclose里的重连逻辑。
正确做法：
-
onerror中只做日志和轻量降级（如切换备用地址），不立即重试 - 把重连统一收口到
onclose，因为只有这里才能拿到真实断连原因（event.code） - 对
event.code === 1006（abnormal closure）和1011（internal error）优先重连，1000（normal closure）则跳过
心跳检测要自己实现，不能依赖onmessage保活
仅靠业务消息收发无法保证连接活性——防火墙、Nginx、云厂商SLB常配置proxy_read_timeout（默认60秒），空闲连接会被静默切断。前端必须主动发心跳。
建议方案：
- 每
25000ms发送一次自定义ping消息（非 WebSocket 协议级 ping，避免被中间设备拦截） - 服务端收到后必须返回
{ type: 'pong', id: xxx }，前端比对id防重放 - 连续
2次未收到pong，视为连接失效，主动ws.close(4998, 'heartbeat timeout') - 心跳定时器必须在
onopen后启动，在onclose前清除，避免跨连接残留
容易被忽略的一点：心跳消息体必须足够小（建议< 16字节），且不能触发业务层日志，否则高并发下日志写入反而成为瓶颈。
