前端 WebSocket 断线重连完整流程：心跳检测、退避重试和消息补发

前端接入 WebSocket 时，最容易低估的不是“怎么连上”，而是“断开以后怎么恢复”。网络切换、浏览器休眠、服务端重启、移动端弱网，都会让连接进入不可用状态。如果只在页面初始化时连一次，线上很容易出现消息不刷新、状态不同步、重复弹通知等问题。

这篇文章按完整工作流整理一套前端 WebSocket 断线重连方案：从页面初始化、建立连接、心跳检测、退避重试，到恢复订阅和离线消息补发。目标是让实时通信可恢复、可观测、可控制。

目标和边界：先区分实时展示和可靠消息

先把边界定清楚。WebSocket 适合做实时通知、在线状态、订单进度、客服消息、行情推送等场景。但不同场景对“消息丢失”的容忍度不一样。在线状态少一条通常可以靠下一次全量状态修正；订单支付成功消息如果漏了，就必须有服务端状态查询兜底。

本文讨论的是前端侧的连接恢复流程。它能解决断线重连、心跳保活、离线期间临时消息排队、重连后恢复订阅这些问题。但如果业务要求消息绝对不丢，仍然需要服务端提供消息 ID、确认机制和历史消息拉取接口。

先说结论：重连不是 while 循环，而是状态机

稳定的重连流程应该围绕状态机设计：连接中、已连接、断开、等待重试、已销毁。每次状态变化都必须有明确入口，避免多个定时器同时重连，也避免页面销毁后连接还在后台运行。

推荐的主线是：页面初始化时建立连接；连接成功后启动心跳；心跳超时或连接关闭时进入等待重试；重连成功后恢复订阅；离线期间需要发送的消息进入队列，重连成功后按顺序补发。

全流程总览：从初始化到恢复订阅

下面这张图展示连接生命周期。重点不是“断了就连”，而是每一步都有检查点：初始化配置、连接成功、心跳检测、断线重连、恢复订阅。

阶段 1：管理连接状态

目标：先避免重复连接。最少需要维护一个状态字段，区分 idle、connecting、open、waiting、closed。

const socketState = {
  status: 'idle',
  ws: null,
  retryCount: 0,
  retryTimer: null,
  heartbeatTimer: null,
  waitPongTimer: null
};

function connectSocket(url) {
  if (socketState.status === 'connecting' || socketState.status === 'open') {
    return;
  }

  socketState.status = 'connecting';
  const ws = new WebSocket(url);
  socketState.ws = ws;

  ws.onopen = () => {
    socketState.status = 'open';
    socketState.retryCount = 0;
    startHeartbeat();
    restoreSubscriptions();
    flushMessageQueue();
  };

  ws.onclose = () => {
    stopHeartbeat();
    scheduleReconnect(url);
  };

  ws.onerror = () => {
    ws.close();
  };
}

这一阶段的检查点是：任何时候只能有一个有效连接入口。按钮点击、路由切换、登录态刷新都可能触发重连，如果没有状态保护，很容易同时创建多个 WebSocket。

阶段 2：用心跳发现半开连接

有些断线不会立刻触发 onclose，比如网络切换、代理层异常、浏览器休眠恢复。心跳的作用是主动确认连接是否还活着。

function startHeartbeat() {
  clearInterval(socketState.heartbeatTimer);

  socketState.heartbeatTimer = setInterval(() => {
    if (socketState.ws?.readyState !== WebSocket.OPEN) {
      return;
    }

    socketState.ws.send(JSON.stringify({ type: 'ping', time: Date.now() }));

    clearTimeout(socketState.waitPongTimer);
    socketState.waitPongTimer = setTimeout(() => {
      socketState.ws?.close();
    }, 8000);
  }, 15000);
}

function handleMessage(raw) {
  const data = JSON.parse(raw.data);
  if (data.type === 'pong') {
    clearTimeout(socketState.waitPongTimer);
    return;
  }

  handleBusinessMessage(data);
}

检查点有两个：心跳间隔不要太短，避免无意义流量；等待 pong 的超时时间要比正常网络抖动略宽，避免弱网下频繁误判。

阶段 3：退避重试，避免重复重连

断线后不能立刻无限重连。服务端重启或网络断开时，前端大量页面同时重试，会让服务端恢复更慢。推荐使用递增等待时间，并设置最大间隔。

function scheduleReconnect(url) {
  if (socketState.status === 'closed') {
    return;
  }

  socketState.status = 'waiting';
  clearTimeout(socketState.retryTimer);

  const delay = Math.min(30000, 1000 * Math.pow(2, socketState.retryCount));
  socketState.retryCount += 1;

  socketState.retryTimer = setTimeout(() => {
    connectSocket(url);
  }, delay);
}

这个阶段的检查点是：页面销毁或用户退出登录时，必须把状态改成 closed，并清理定时器。否则用户离开页面后，后台仍然可能继续重连。

阶段 4：恢复订阅和补发消息

连接恢复只是第一步。真正让业务恢复正常，还要重新订阅频道，并处理断线期间积压的前端消息。

可以维护一个轻量离线队列。连接断开时，允许临时消息进入队列；连接恢复后，按顺序发送，并等待服务端 ACK。超过保留时长的消息直接丢弃，避免补发过期操作。

const pendingMessages = [];

function sendMessage(payload) {
  const message = {
    id: crypto.randomUUID(),
    createdAt: Date.now(),
    payload
  };

  if (socketState.ws?.readyState === WebSocket.OPEN) {
    socketState.ws.send(JSON.stringify(message));
    return;
  }

  pendingMessages.push(message);
}

function flushMessageQueue() {
  const now = Date.now();
  const aliveMessages = pendingMessages.filter(item => now - item.createdAt 

如果业务消息不能重复处理，服务端必须按 id 做幂等。前端只负责补发，不能假设每条消息都只会被服务端处理一次。

我的推荐流程

1. 先定义连接状态，不允许多入口重复创建 WebSocket。
2. 连接成功后启动心跳，收到 pong 后清理等待计时。
3. 心跳超时或连接关闭时进入等待重试状态。
4. 使用退避间隔控制重连频率，页面销毁时清理所有定时器。
5. 重连成功后恢复订阅，而不是只恢复底层连接。
6. 离线消息进入队列，重连后按顺序补发，过期消息丢弃。
7. 重要业务消息必须依赖服务端 ACK 和幂等 ID。

容易踩坑

• 只监听 onclose：半开连接可能不会及时触发关闭，需要心跳主动发现。
• 无限立即重连：网络故障时会产生大量无效连接请求。
• 页面销毁不清定时器：后台仍然重连，导致资源泄漏和重复消息。
• 重连成功但不恢复订阅：底层连接恢复了，业务频道仍然没有消息。
• 补发消息没有 ID：服务端无法判断重复消息，容易产生重复操作。

速查表

总结

前端 WebSocket 断线重连的核心不是“断了再连一次”，而是把连接当成一套可恢复流程：状态机限制入口，心跳发现异常，退避控制重试，恢复订阅接回业务，离线队列处理补发。

如果你的业务只要求实时展示，这套流程已经能解决大部分线上抖动；如果业务要求消息可靠，还需要服务端配合 ACK、消息 ID 和历史拉取接口。前端重连负责恢复通道，最终一致性仍然要靠前后端一起设计。