用途:排查 WebSocket 帧头类错误。适用症状包括 Invalid WebSocket frame: RSV1 must be clear、WS_ERR_UNEXPECTED_RSV1、Invalid frame header、连接后立即以 1006 断开、服务端记录成功但客户端收到乱码。资料指出这类错误常非帧损坏,而是原始 HTTP 被写入已升级套接字,多因同一 HTTP 服务器上挂载了多个 WebSocketServer 实例。
主要能力:提供症状—原因—修复对照表;解释多实例冲突原理:两个实例都添加 upgrade 监听,客户端连 /ws 时两个监听器都触发,未匹配路径的实例调用 abortHandshake(socket, 400),把 “HTTP/1.1 400” 文本写入套接字,首字节 0x48 被解析为 RSV1=1 与 opcode=8,从而报无效帧。
使用方式:改用 noServer: true,并在单一 server.on('upgrade') 中按 URL 路径手动调用各实例的 handleUpgrade,未匹配则 socket.destroy()。可用资料中的 socket.push 钩子打印前 20 字节十六进制及 FIN/RSV1/Opcode 位,判断是否收到原始 HTTP。关键十六进制:81 文本帧、82 二进制帧、88 关闭帧、48545450 即 “HTTP”。
限制:资料仅针对 Node.js 的 ws 库场景,未提供其他语言或框架方案;未提及安装命令、收费与平台信息;修复后需自行按检查清单验证,如 RSV1 为 false、扩展头为 NONE、原始帧无 HTTP/1.1、收发负载长度一致等。