name: debugging-websocket-issues description: 当遇到WebSocket错误，如“无效帧头”、“RSV1必须清除”或“WS_ERR_UNEXPECTED_RSV_1”时使用 - 涵盖多个WebSocketServer冲突、压缩问题及原始帧调试技术 tags: websocket, debugging, ws, node

调试WebSocket问题

概述

WebSocket“无效帧头”错误通常源于原始HTTP被写入已升级的套接字，而非实际帧损坏。最常见的原因是多个WebSocketServer实例在同一HTTP服务器上发生冲突。

使用时机

错误：无效的WebSocket帧：RSV1必须清除
错误：WS_ERR_UNEXPECTED_RSV_1
错误：无效帧头
WebSocket连接后立即断开，代码1006
服务器日志显示成功，但客户端收到乱码数据

快速参考

症状	可能原因	修复方法
RSV1必须清除	同一服务器上多个WSS或压缩不匹配	使用`noServer: true`模式
十六进制以`48545450`开头	WebSocket上出现原始HTTP（0x48=‘H’）	检查冲突的升级处理器
代码1006，无原因	异常关闭，通常是服务器端中止	检查`abortHandshake`调用
隔离测试正常，应用中失败	其他内容写入套接字	审计所有升级监听器

多个WebSocketServer的Bug

问题

当将多个WebSocketServer实例附加到同一HTTP服务器并使用server选项时：

// ❌ 错误 - 两个服务器都添加升级监听器，导致冲突
const wss1 = new WebSocketServer({ server, path: '/ws' });
const wss2 = new WebSocketServer({ server, path: '/ws/other' });

发生过程：

客户端连接到/ws
两个升级处理器都触发（Node.js EventEmitter调用所有监听器）
wss1匹配路径，成功处理升级
wss2不匹配，调用abortHandshake(socket, 400)
原始HTTP/1.1 400 Bad Request被写入现已升级为WebSocket的套接字
客户端收到HTTP文本作为WebSocket帧数据
第一个字节0x48（‘H’）被解释为：RSV1=1，操作码=8 → 无效帧

解决方案

使用noServer: true并手动路由升级：

// ✅ 正确 - 单个升级处理器路由到正确的服务器
const wss1 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
const wss2 = new WebSocketServer({ noServer: true, perMessageDeflate: false });

server.on('upgrade', (request, socket, head) => {
  const pathname = new URL(request.url || '', `http://${request.headers.host}`).pathname;

  if (pathname === '/ws') {
    wss1.handleUpgrade(request, socket, head, (ws) => {
      wss1.emit('connection', ws, request);
    });
  } else if (pathname === '/ws/other') {
    wss2.handleUpgrade(request, socket, head, (ws) => {
      wss2.emit('connection', ws, request);
    });
  } else {
    socket.destroy();
  }
});

调试技术

原始帧检查

挂钩到套接字以查看实际接收的字节：

ws.on('open', () => {
  const socket = ws._socket;
  const originalPush = socket.push.bind(socket);

  socket.push = function(chunk, encoding) {
    if (chunk) {
      console.log('前20字节（十六进制）：', chunk.slice(0, 20).toString('hex'));
      const byte0 = chunk[0];
      console.log(`FIN: ${!!(byte0 & 0x80)}, RSV1: ${!!(byte0 & 0x40)}, 操作码: ${byte0 & 0x0f}`);

      // 检查是否实际上是HTTP文本
      if (chunk.slice(0, 4).toString() === 'HTTP') {
        console.log('*** 在WebSocket上收到原始HTTP ***');
      }
    }
    return originalPush(chunk, encoding);
  };
});

关键十六进制模式

81 = FIN + 文本帧（正常）
82 = FIN + 二进制帧（正常）
88 = FIN + 关闭帧（正常）
48545450 = “HTTP” - WebSocket上的原始HTTP（错误！）
c1或类似第6位设置的字节 = 压缩帧（RSV1=1）

常见错误

错误	结果	修复方法
多个WSS使用`server`选项	HTTP 400写入套接字	使用`noServer: true`
`perMessageDeflate: true`（旧版ws默认）	帧上设置RSV1	显式设置`perMessageDeflate: false`
未检查升级头	错过压缩协商	记录`sec-websocket-extensions`头
假设RSV1错误=压缩	可能是原始HTTP	检查字节是否解码为ASCII “HTTP”

验证清单

修复后，验证：

[ ] 帧检查中RSV1: false
[ ] 升级响应中Extensions header: NONE
[ ] 原始帧数据中没有HTTP/1.1
[ ] 接收的消息与发送的有效载荷大小匹配
[ ] 多播正常工作（测试间隔发送）