WebSocket 从原理到实战：握手、心跳、Nginx 部署避坑指南

做前端这几年，只要一碰“实时推送”需求，我的第一反应永远不是轮询，而是 WebSocket。在线客服、股票行情看板、后台任务执行进度，我都是用这套方案把服务端数据实时推到浏览器端。很多同学第一次接触时，往往是打开控制台刷到一整片报错：stream disconnected before completion、WebSocket closed by server before response，页面偶尔还直接卡死，最后不得不怀疑人生。这篇文章我想把 JavaScript 里 WebSocket 从原理到实践、从浏览器到服务端、从开发环境到 Nginx 反代上线的完整链路整理一遍。无论你是刚准备入门实时通信，还是已经踩过几个坑，都能在这里找到可以马上抄走的方案。

1. 为什么实时通信场景绕不开 WebSocket

1.1 HTTP 轮询差在哪

先说最传统的方式：轮询。前端写一个 setInterval，每隔两秒发一次 GET 请求，服务端返回最新数据。这个方案实现成本极低，但代价很明显：大多数请求返回的数据根本没有任何变化，白白浪费带宽；请求频率越高延迟越低，服务器压力却越大；请求频率越低服务器越轻松，延迟又上去了。我见过一个项目，在线人数三百，轮询间隔 1 秒，QPS 直接跑到了三百，实际上真正需要推送的消息每分钟也就几十条。

后来有人发明了长轮询：客户端发一个请求过去，服务端先挂住，等有了新数据再返回，客户端收到后再立刻发下一个请求。这确实把无效请求的数量降下来了，但连接在服务端长时间挂着，每个连接都要占用一个 socket、一个线程或者协程资源，连接数一多依然顶不住。而且长轮询本质上还是一条“单向管道”，服务端不能主动往客户端推数据，消息要是恰好在这两次请求之间产生，客户端还是要等到下一次请求才能拿到。所以长轮询只是缓解了轮询的部分痛点，并没有从根本上改变“请求-响应”这个模型。

1.2 一次搞定握手：从 HTTP 升级为 WebSocket 的完整过程

WebSocket 的思路就完全不同了。它先通过 HTTP 协议完成一次握手，然后升级为 WebSocket 协议，之后连接双方随时都可以往对方发数据，再也不需要一次次建立连接。这个设计很巧妙：它复用了 HTTP 的 80/443 端口，所以防火墙不用额外开端口；同时 Nginx、CDN 这些基础设施也天然认识这个握手过程。

握手过程大概是这样的。客户端发一个 GET 请求，带上 Upgrade: websocket 和 Connection: Upgrade 两个头，同时生成一个 16 字节的随机数做 Base64，放到 Sec-WebSocket-Key 头里。服务端收到后，把这个 Key 拼上一个协议固定的 GUID 字符串 258EAFA5-E914-47DA-95CA-C5AB0DC85B11，做一次 SHA-1 哈希，再 Base64 编码，放到响应头的 Sec-WebSocket-Accept 里返回。如果客户端算出来的结果和服务端一致，握手成功，返回 101 Switching Protocols，之后这条连接就从 HTTP 切换成了 WebSocket。

为什么协议非要给你搞一个校验 Key？最核心的用途是防止普通 HTTP 缓存代理把这个握手请求当成普通 GET 请求缓存下来。有了这个随机 Key 和固定 GUID 的校验，中间层没法伪造响应，也能保证这次 Upgrage 是“对的人在对的地方”。这个设计本身也是一种安全保障，所以千万不要觉得它麻烦就去掉。

1.3 什么场景才值得换这套方案

WebSocket 并不是银弹。如果业务是标准的请求-响应模式，比如查询订单、提交表单、拉取列表，老老实实用 HTTP 就行。HTTP 有无状态、可缓存、可压缩、有成熟的重试语义这些优势，强行上 WebSocket 反而把简单问题复杂化。

真正适合 WebSocket 的场景有三类：

• 服务端主动推送：通知、行情、进度条、日志流转
• 高频双向交互：在线协作编辑、实时游戏、远程控制
• 需要长时间保持在线状态的连接：客服坐席、直播弹幕、物联网设备控制

另外要说一下 SSE（Server-Sent Events）。SSE 走 HTTP，服务端可以单向往客户端推数据，实现简单、自动重连，但它是单向的，客户端想往服务端发消息还是得发 HTTP 请求。WebSocket 是双向的，所以只要明确要双向通信，基本就直接跳过 SSE 考虑 WebSocket 了。

2. 浏览器端从零开始：建立连接、收发消息、心跳保活

2.1 五分钟跑通一个最小 Demo

浏览器端使用 WebSocket 自带原生 API，不用装任何依赖。先给一个最小完整示例：

javascript复制const socket = new WebSocket('ws://localhost:8080/ws');

socket.addEventListener('open', () => {
  console.log('连接已建立');
  socket.send(JSON.stringify({ type: 'join', room: 'demo' }));
});

socket.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('收到消息：', data);
});

socket.addEventListener('close', (event) => {
  console.log('连接已关闭，code=', event.code, 'reason=', event.reason);
});

socket.addEventListener('error', (error) => {
  console.error('发生错误：', error);
});

这里有几个值得注意的细节。socket.onopen、socket.onmessage 这种赋值式写法虽然能用，但我建议用 addEventListener，因为同一个事件可以挂多个监听函数，后续扩展不会互相覆盖。

WebSocket 创建之后会自动开始连接，没有 connect() 方法可以调用。readyState 属性代表当前连接状态，0 是 CONNECTING，1 是 OPEN，2 是 CLOSING，3 是 CLOSED。发消息之前最好判断一下：socket.readyState === WebSocket.OPEN，否则在连接没建立时调用 send() 会直接抛异常。

send() 方法能发送的数据类型包括字符串、Blob、ArrayBuffer、TypedArray、DataView。如果服务端推的是二进制数据，建议把 socket.binaryType 设置成 'arraybuffer'，默认是 'blob'，Blob 在处理二进制协议时没有 ArrayBuffer 那么顺手。

2.2 心跳保活：没有它，连接会被默默掐掉

这是最容易踩坑的地方。你以为连接还活着，其实中间某个代理已经把它关了。

很多网络设备、云负载均衡器、Nginx 都有一个“空闲超时”机制。如果一条连接在指定时间内没有任何数据传输，中间设备就会主动把它断开。Nginx 默认的 proxy_read_timeout 是 60 秒，也就是说，如果你页面挂着什么都不做，超过 60 秒，Nginx 就可能把这条 WebSocket 连接掐掉。重点是：浏览器感知不到服务端或者中间层已经断开，readyState 还会停留在 1（OPEN），直到你下一次真正发消息出去才会触发报错。这在“只是挂着看数据”的场景里，问题会被藏得很深。

解决方式就是在应用层做心跳。浏览器端的 WebSocket API 没有直接暴露协议层的 ping/pong 帧控制能力，所以常规做法是发业务心跳消息：定时发送 { "type": "ping" }，服务端收到后返回 { "type": "pong" }。下面是一个基础实现：

javascript复制let heartbeatTimer = null;

function startHeartbeat(socket) {
  stopHeartbeat();
  heartbeatTimer = setInterval(() => {
    if (socket.readyState === WebSocket.OPEN) {
      socket.send(JSON.stringify({ type: 'ping' }));
    }
  }, 30000);
}

function stopHeartbeat() {
  if (heartbeatTimer) {
    clearInterval(heartbeatTimer);
    heartbeatTimer = null;
  }
}

心跳间隔要小于中间设备的空闲超时时间。按经验，心跳间隔设为空闲超时的一半比较安全。比如 Nginx 超时 60 秒，心跳就 30 秒发一次；如果设成 55 秒，万一有一次网络抖动心跳丢了，连接就直接被掐了。

补充一点：在服务端，Node 的 ws 库可以用原生 ws.ping() 发协议层的 ping 帧，浏览器端会自动回 pong 帧。这是因为 RFC 6455 规定收到 ping 必须回复 pong，浏览器底层已经实现了。所以服务端用协议层 ping/pong 做探活，前端用业务心跳刷新数据，两者可以配合使用。

2.3 自动重连没那么简单：退避和抖动

断线重连是 WebSocket 项目的刚需。最简单的做法是 onclose 里直接 setTimeout(connect, 1000)，但这种写法上线后很容易出事。设想一下：服务端发布重启，几百个用户同时断线，一秒钟后几百个客户端同时发起重连，服务端刚启动就被打了一波“重连风暴”。

比较规范的做法是指数退避加随机抖动。第一次重连等 1 秒，第二次 2 秒，第三次 4 秒，指数增长，同时每次加一个随机偏移，让各客户端的重连时间点尽量散开：

javascript复制let retryCount = 0;
const MAX_RETRY_DELAY = 30000;

function connect(url) {
  const ws = new WebSocket(url);

  ws.addEventListener('open', () => {
    retryCount = 0;
    startHeartbeat(ws);
  });

  ws.addEventListener('close', () => {
    stopHeartbeat();
    const delay = Math.min(1000 * Math.pow(2, retryCount), MAX_RETRY_DELAY) + Math.random() * 1000;
    retryCount += 1;
    setTimeout(() => connect(url), delay);
  });
}

另外，记得监听 visibilitychange。浏览器为了省电，会把后台标签页的定时器节流，心跳定时器可能被延后甚至不执行。用户切回页面时，一定要立刻检查连接状态，发现不对马上重连：

javascript复制document.addEventListener('visibilitychange', () => {
  if (!document.hidden && ws.readyState !== WebSocket.OPEN) {
    reconnect();
  }
});

2.4 可以直接抄的轻量连接管理器

把连心跳、重连、消息回调封装到一起，平时开发直接复用：

javascript复制class ReconnectingWebSocket {
  constructor(url, options = {}) {
    this.url = url;
    this.heartbeatInterval = options.heartbeatInterval || 30000;
    this.maxRetryDelay = options.maxRetryDelay || 30000;
    this.listeners = {};
    this.retryCount = 0;
    this.manualClose = false;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url);

    this.ws.addEventListener('open', () => {
      this.retryCount = 0;
      this.emit('open');
      this.startHeartbeat();
    });

    this.ws.addEventListener('message', (event) => {
      this.emit('message', event.data);
    });

    this.ws.addEventListener('close', (event) => {
      this.stopHeartbeat();
      this.emit('close', event);
      if (!this.manualClose) {
        this.scheduleReconnect();
      }
    });

    this.ws.addEventListener('error', (error) => {
      this.emit('error', error);
    });
  }

  scheduleReconnect() {
    const delay = Math.min(1000 * Math.pow(2, this.retryCount), this.maxRetryDelay) + Math.random() * 1000;
    this.retryCount += 1;
    setTimeout(() => this.connect(), delay);
  }

  startHeartbeat() {
    this.stopHeartbeat();
    this.heartbeatTimer = setInterval(() => {
      if (this.ws.readyState === WebSocket.OPEN) {
        this.ws.send(JSON.stringify({ type: 'ping' }));
      }
    }, this.heartbeatInterval);
  }

  stopHeartbeat() {
    if (this.heartbeatTimer) {
      clearInterval(this.heartbeatTimer);
      this.heartbeatTimer = null;
    }
  }

  send(data) {
    if (this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(data);
    }
  }

  close() {
    this.manualClose = true;
    this.ws.close();
  }

  on(event, callback) {
    if (!this.listeners[event]) this.listeners[event] = [];
    this.listeners[event].push(callback);
  }

  emit(event, ...args) {
    (this.listeners[event] || []).forEach((fn) => fn(...args));
  }
}

这个管理器比较轻量，核心解决两件事：连接状态的统一管理，以及所有关闭场景下的自动重连。后面工程化章节我还会讲怎么给它加消息等待队列和连接去重。

3. 后端配合：Node.js 原理解析与 WS 库实战

3.1 先自己写一次握手，搞懂协议

前端写得再熟，不了解协议，碰到握手失败一样抓瞎。我们先看服务端是怎么处理的。用 Node.js 原生模块实现一个最简握手：

javascript复制const http = require('http');
const crypto = require('crypto');

const server = http.createServer((req, res) => {
  res.writeHead(200);
  res.end('这是普通 HTTP 服务');
});

server.on('upgrade', (req, socket) => {
  const key = req.headers['sec-websocket-key'];
  const accept = crypto
    .createHash('sha1')
    .update(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11')
    .digest('base64');

  socket.write(
    'HTTP/1.1 101 Switching Protocols\r\n' +
    'Upgrade: websocket\r\n' +
    'Connection: Upgrade\r\n' +
    `Sec-WebSocket-Accept: ${accept}\r\n\r\n`
  );

  socket.on('data', (data) => {
    // 到这里收到的就是 WebSocket 帧，需要自行解析
  });
});

server.listen(8080);

握手成功之后，后续的通信就不再是普通 HTTP 报文了。WebSocket 协议定义了一套帧格式，每帧数据包含 FIN、opcode、掩码标志、载荷长度、掩码密钥、载荷数据这几部分。客户端发给服务端的帧必须带掩码（MASK=1），否则服务端应该以协议错误关闭连接。为什么要强制客户端加掩码？这是为了防止“缓存污染攻击”，简单理解就是防止攻击者精心构造 WebSocket 帧内容，让中间代理误认为这是一段有效的 HTTP 响应从而污染缓存。服务端发给客户端的帧不需要掩码。

这个阶段如果完全自己实现解析，要处理分片、压缩、控制帧、关闭握手，工作量不小。所以实际项目里我不会裸写协议解析，直接用成熟的库，但把握手流程了解清楚，后面排查问题会快很多。

3.2 用 ws 库写一个带心跳和房间广播的服务端

Node 生态最常用的是 ws 库，安装一行命令：

bash复制npm install ws

一个带心跳检测和房间广播的基础服务端：

javascript复制const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 8080 });
const rooms = new Map(); // 房间名 -> Set<WebSocket>

function heartbeat() {
  this.isAlive = true;
}

wss.on('connection', (ws, req) => {
  ws.isAlive = true;
  ws.on('pong', heartbeat);

  ws.on('message', (data) => {
    let msg;
    try {
      msg = JSON.parse(data.toString());
    } catch (err) {
      return;
    }

    if (msg.type === 'join') {
      if (!rooms.has(msg.room)) {
        rooms.set(msg.room, new Set());
      }
      rooms.get(msg.room).add(ws);
    }

    if (msg.type === 'ping') {
      ws.send(JSON.stringify({ type: 'pong' }));
    }

    if (msg.type === 'chat' && msg.room) {
      broadcast(msg.room, {
        type: 'chat',
        content: msg.content,
        time: Date.now(),
      });
    }
  });
});

function broadcast(room, message) {
  const clients = rooms.get(room);
  if (!clients) return;
  const payload = JSON.stringify(message);
  clients.forEach((client) => {
    if (client.readyState === WebSocket.OPEN) {
      client.send(payload);
    }
  });
}

// 每 30 秒检查一次僵尸连接
const interval = setInterval(() => {
  wss.clients.forEach((ws) => {
    if (ws.isAlive === false) {
      ws.terminate();
      return;
    }
    ws.isAlive = false;
    ws.ping();
  });
}, 30000);

wss.on('close', () => {
  clearInterval(interval);
});

这里的 terminate() 和 close() 是有区别的。close() 会先走 WebSocket 关闭握手，发一个 close 帧，再等对端响应，是“优雅关闭”；terminate() 是直接销毁底层 socket，是“强杀”。对已经确认失去响应的僵尸连接，用 terminate() 更干净，避免连接一直占着资源不释放。

房间广播这边，如果只在一个 Node 进程内跑，用 Map 管理房间完全够用。但一旦服务横向扩展成多个实例，客户端连接分散在不同进程里，进程 A 收到消息只能在进程 A 内广播，连在进程 B 上的客户端收不到。这个场景需要引入 Redis Pub/Sub 做跨实例广播，具体方案我会在下一章展开。

3.3 服务端库怎么选

WebSocket 协议是 RFC 6455 标准，只要按协议实现，跨语言是天然互通的。Node 端选择比较多：

如果你在一个纯前端团队，后端也用 Node，那我建议直接用 ws，简单可控，不引入额外概念。Socket.IO 虽然方便，但它不是纯 WebSocket，底层有自己的一套事件协议，一旦需要和其他语言的后端联调，就要额外适配它的协议。Java Spring Boot 集成 WebSocket 时有个容易踩的坑：@ServerEndpoint 的实例生命周期不受 Spring 容器管理，你要在 Endpoint 里使用 Spring Bean，不能用 @Autowired 直接注入，得通过静态字段或者 SpringContextHolder 拿。这就是典型的“看着简单，真跑起来才发现资料不对”的情况。

4. 扛住生产环境：Nginx 反代 WebSocket 与连接保活

4.1 Nginx 最少必要配置

开发环境直连后端没问题，线上一般会在前面挡一层 Nginx，负责 WSS 证书终止、负载均衡、灰度发布。Nginx 从 1.3.13 开始就支持 WebSocket 反代了，关键配置如下：

nginx复制map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream ws_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /ws/ {
        proxy_pass http://ws_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

这里 map 的作用是把 $http_upgrade 映射成 $connection_upgrade。如果客户端请求带了 Upgrade: websocket，Nginx 就把 Connection 设成 upgrade，把 WebSocket 握手头原样传给后端；如果是不带 Upgrade 的普通请求，Connection 就设成 close，保持 HTTP 的默认行为。不写这个 map，直接把 proxy_set_header Connection upgrade 写死，也行，但那样普通 HTTP 请求也会带上 Connection: upgrade，行为不规范。

proxy_read_timeout 和 proxy_send_timeout 一定要调大。Nginx 默认 60 秒，也就是说即使 WebSocket 建立成功了，如果 60 秒内双方没有数据往来，Nginx 会主动断开。上一章说前端要做心跳，心跳间隔 30 秒，那 Nginx 这里至少设到 60 秒以上，我给 300 秒是因为有些业务允许客户端长时间不产生业务数据，只有心跳在跑，300 秒足够宽裕。

4.2 云环境、K8s 里连接为什么更容易断

很多人在本地开发跑得好好的，一上云就频繁掉线，这通常不是代码问题，是链路里的中间层在作祟。云厂商的负载均衡器（SLB/ALB）有自己的空闲连接超时配置，有些默认是 30 秒，比 Nginx 还激进。云控制台里的“连接空闲超时”和“连接空闲超时（秒）”要主动调大，和 Nginx 保持同一量级。

K8s 环境还有另一个断连场景：滚动更新。旧 Pod 被销毁时，连在旧 Pod 上的 WebSocket 连接全部断开。客户端只能感知到 onclose，没有太多补救空间。这时候客户端重连机制的价值就体现出来了。如果希望旧 Pod 在销毁前给存量连接一个收尾缓冲，可以调整 terminationGracePeriodSeconds，默认 30 秒一般也够用了。

多实例部署的时候，还要处理跨实例广播。我在 3.2 节写的房间广播只在本进程内有效。多实例方案很简单：用 Redis Pub/Sub 转发消息，任何实例收到消息后 publish 到 Redis，所有实例订阅同一个 channel，然后各自广播给自己的本地连接。

javascript复制const redis = require('redis');

const pub = redis.createClient();
const sub = redis.createClient();

sub.subscribe('ws_broadcast');
sub.on('message', (channel, message) => {
  const { room, payload } = JSON.parse(message);
  broadcastLocal(room, payload);
});

function broadcastAcrossInstances(room, payload) {
  broadcastLocal(room, payload);
  pub.publish('ws_broadcast', JSON.stringify({ room, payload }));
}

这样只要保证一条消息在每个实例本地只会广播一次，就能实现全局限流、全量广播。

4.3 生产环境部署检查清单

上线之前，建议按下面这份清单逐项自查：

• TLS 证书是否有效，浏览器是否用 wss:// 访问
• Nginx 的 proxy_set_header Upgrade 和 Connection 是否正确
• Nginx 的 proxy_read_timeout 是否大于心跳间隔的两倍
• 云负载均衡器的空闲超时是否调整过
• 服务端心跳检测和僵尸连接清理是否开启
• 多实例部署是否接入了 Redis Pub/Sub
• 连接日志是否记录了连接建立与关闭的关键链路
• 是否配置了 WebSocket 连接数的监控告警

每次上线前花十分钟过一遍这个清单，能省掉大量线上问题。

5. 常见报错与排查技巧实录

5.1 握手失败的典型报错：closed by server before response

热词里出现频率很高的 stream disconnected before completion 和 WebSocket closed by server before response，本质是同一种现象：客户端发起了 WebSocket 握手请求，但服务端还没有正常返回 101 响应，连接就断了。这种情况浏览器 WebSocket 对象的 error 和 close 事件会先后触发，但控制台显示的报错信息往往很含糊。

排查步骤我一般按这个顺序来：

1. 确认后端服务是不是真的在监听对应端口和路径，是不是启动失败了
2. 用浏览器 Network 面板看握手请求的状态码，是不是 101
3. 确认中间有没有 Nginx 或者其他代理，Upgrade 头有没有被透传
4. 确认服务端日志里有没有抛出异常
5. 用命令行工具直接打一次握手请求

bash复制curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  http://localhost:8080/ws

如果返回 HTTP/1.1 101 Switching Protocols，说明后端握手服务正常，问题大概率在浏览器到后端之间的链路；如果返回 404、502、403，就按对应状态码继续查。403 尤其要关注，服务端可能在握手阶段做了鉴权拒绝；502 则说明 Nginx 连不上后端。

5.2 开发环境常见坑：javascript:void(0) 报错缠绕不清

搜索热词里出现了 javascript:void(0)，很多同学一看到控制台报错就以为是 WebSocket 的问题。实际上这个和 WebSocket 没有任何直接关系，但它确实经常出现在同一个页面里，干扰排查。

javascript:void(0) 通常出现在 <a href="javascript:void(0)"> 这种写法里，作用是让这个链接点击后不跳转、不刷新页面。浏览器在某些安全策略下会拦截这类内联 JavaScript 执行，于是控制台会报出和 javascript: 协议相关的错误。如果你是通过点击一个“发送消息”按钮发现 WebSocket 页面卡死的，很容易把这两个问题搅在一起。

我的建议是从源头避免这种写法。事件绑定用 button 元素，或者直接在 click 事件里 preventDefault()，不要依赖 javascript:void(0)。还有一个反向提醒：javascript:void(document.title=document.cookie) 这类出现在地址栏的代码，本质是恶意的 JavaScript 注入尝试，开发调试时千万不要在正式页面里执行这类内容。排查问题要聚焦，别让这些噪音浪费时间。

5.3 页面崩溃、浏览器卡死，问题可能出在数据消费

另一个热词是“WebSocket 导致浏览器崩溃”。说实话，WebSocket 协议本身不会导致浏览器崩溃，真正导致卡死的是消息消费端的代码写崩了。我在一个行情项目里遇到过一模一样的情况：WebSocket 每秒推送几千条消息，前端每条消息都直接生成一个 DOM 节点往上挂，页面打开十分钟，内存占用直接冲上几百 MB，最后浏览器把整个标签页杀掉。

根本原因不是消息多，而是数据没有被节流和合并。实时的流式数据，尤其是行情、日志、监控指标这类，DOM 更新频率不需要等于消息推送频率。人眼一秒能感知的变化是有限的，屏幕刷新率也只有 60fps，HTTP 推 1000 条消息，DOM 每帧最多更新一次就够了。可以用一个简单的合并节流：

javascript复制let pendingMessages = [];
let rendering = false;

socket.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  pendingMessages.push(data);

  if (!rendering) {
    requestAnimationFrame(flush);
    rendering = true;
  }
});

function flush() {
  const batch = pendingMessages;
  pendingMessages = [];
  rendering = false;

  // 只在界面上渲染最新的几条或者聚合结果
  renderList(batch);
}

另外注意消息积压问题。如果 onmessage 里做的是重活，比如解析大 JSON、执行复杂计算，新消息会不断排队，内存持续上涨。可以考虑把解析和计算丢到 Web Worker 里，主线程只负责渲染。再配合服务端限频或者前端做采样，把消息量降下来，页面就稳了。

5.4 问题排查速查表

6. 从能用走向好用：工程化几件事

6.1 连接管理器封装进阶：消息等待队列和去重

我在 2.4 节给的连接管理器只解决了重建连接的问题，但断线期间用户的操作消息全部丢掉了。对即时聊天、协同编辑这类场景，消息丢失是不能接受的。可以在连接管理器里加一个待发送队列：断线期间 send() 的消息先存起来，重连成功后再统一发出。

javascript复制send(data) {
  if (this.ws.readyState === WebSocket.OPEN) {
    this.ws.send(data);
  } else {
    this.pendingQueue.push(data);
    if (this.pendingQueue.length > 100) {
      this.pendingQueue.shift(); // 防内存爆炸，丢最旧的消息
    }
  }
}

flushQueue() {
  while (this.pendingQueue.length > 0 && this.ws.readyState === WebSocket.OPEN) {
    this.ws.send(this.pendingQueue.shift());
  }
}

这里有一个实际问题：重连之后，哪些消息需要重发、哪些消息服务端已经处理过了，靠队列本身是没法保证的。最稳的方案是给消息加一个唯一 ID，在服务端做幂等处理。客户端每次生成一个 msgId，重发时带上同一个 msgId，服务端用 Redis 或者内存缓存记录最近处理过的消息 ID，如果发现重复就直接丢弃，返回原来的处理结果。这个方案比“客户端和服务端反复对账”简单得多。

还可以给连接本身打一个连接 ID。第一次连接时生成一个 connectionId，重连时把旧的 connectionId 带上，服务端就能识别出“这是同一条逻辑连接的重新建立”，方便清理旧连接上的订阅状态、续接没有推送完的数据。这个设计在客户端断线重连后能明显减少数据错乱。

6.2 安全与鉴权细节

浏览器端的 new WebSocket(url) 没办法像 fetch 那样自定义 Header，这是 WebSocket API 的一个限制。所以常见的鉴权做法是把 token 放到 URL 查询参数里：

javascript复制const token = getToken();
const socket = new WebSocket(`wss://example.com/ws?token=${encodeURIComponent(token)}`);

服务端在握手阶段取出 token 做校验，校验失败直接关闭连接，不要给任何业务数据。这里要注意两个坑：一是 URL 参数会出现在 Nginx 日志、浏览器历史、Referer 里，token 泄漏风险比放在 Header 里高，所以 token 有效期要短，建议 10 分钟级别；二是不要让前端把 token 放 URL 就完事，服务端要做来源校验，至少校验 Origin 头，防止别的恶意页面偷偷往你的 WebSocket 服务建立连接。生产环境必须用 wss://，否则数据在网络上就是明文传输。

6.3 协议设计：版本、心跳、错误码、压缩

初学者的常见做法是“收到什么字符串就展示什么字符串”，但项目上线前，协议设计一定要提前定好。我建议所有消息统一封装成 JSON：

json复制{
  "v": 1,
  "type": "chat",
  "id": "msg_20241001120000_001",
  "ts": 1727769600000,
  "data": {}
}

v 是协议版本号，客户端和服务端做兼容判断时全靠它；id 是消息唯一 ID，用来做幂等和请求响应关联；ts 是时间戳，排查延迟问题时很有用；type 区分业务类型。心跳消息也走同一个结构，只是 type 是 ping / pong。如果消息量很大，JSON 的冗余率确实可观，可以考虑切到 MessagePack 或者 Protobuf，静态字段直接改成二进制协议。但要不要做这一步，取决于你的瓶颈是不是带宽。大多数业务场景，JSON 加压缩已经够用。

关于关闭连接的 code，WebSocket 协议里 1000 表示正常关闭，1001 表示服务端要下线，1002 协议错误。自定义业务错误建议用 4000-4999 这个私有区间，比如 4001 表示 token 过期，4002 表示服务端主动踢人。客户端收到 code 之后提示用户重新登录还是自动重连，区分得很清楚。

最后说点个人的体会。我接手过不少 WebSocket 项目，真正让系统稳定的，往往不是连接建立那一下，而是所有断开场景都能被感知、被重连、被恢复。连接 ID、心跳、重连队列这些看似不起眼的基建，才是线上少报警的关键。再分享一个小技巧：上线前做一次断电测试，把服务端直接 kill 掉，观察客户端是多快发现连接断了、多久恢复、恢复后消息是否乱序重复。这比看再多文档都有用。