WebSocket文档需明确URL参数（如?token=abc123）为认证入口、强制声明子协议值（如Sec-WebSocket-Protocol: chat-v2）、标注关闭码业务含义（如4001=token过期），并用JSON Schema示例定义消息格式，避免前端抓包反推。
WebSocket文档怎么写才不被前端骂
WebSocket文档不是HTTP接口的简单复制粘贴。它必须明确交代“连接前要带什么”“连上后发什么格式”“断开时可能返回哪些码”。否则前端拿到文档，第一件事就是抓包反推你的协议设计。
关键点在于：URL参数即认证入口、子协议（Sec-WebSocket-Protocol）需显式声明、关闭码必须标注业务含义。
-
?token=abc123&client_id=456是合法且推荐的鉴权方式，不要写“请在Header中传Authorization”——浏览器 WebSocket 构造函数根本不支持设置自定义 Header - 若服务端要求
Sec-WebSocket-Protocol: chat-v2，文档里必须写死这个字符串，不能只写“支持子协议” - 关闭帧状态码如
1001（离开）、4001（token过期）、4003（权限不足），每种都要配一句话说明，前端靠它做错误分类和重连策略 - 消息体格式建议用 JSON Schema 示例，而非纯文字描述。比如
{"type":"join","room":"public"}比“发送加入房间指令”更防歧义
wscat 命令行调试时为什么连不上
wscat 是最轻量也最容易翻车的工具——它不帮你补协议头、不自动重连、不解析关闭原因，只忠实转发原始帧。连不上大概率是握手阶段就失败了。
常见错误现象：Error: unexpected server response (400) 或直接卡住无响应。
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 检查地址是否带
ws://或wss://前缀，wscat -c http://...必然失败 - 需要传参时，必须拼在 URL 后：
wscat -c "wss://api.example.com/ws?token=xyz"，不能用-H传 Header - 若服务端校验
Origin，加--origin https://example.com；若要求特定子协议，加--protocol chat-v2 - 遇到 TLS 错误（如 self-signed cert），临时加
--no-check，但生产环境务必禁用
Chrome DevTools 里看不到 Messages 标签
不是你没找到，是 Chrome 只显示“当前页面已建立的 WebSocket 连接”，前提是：该连接必须由页面 JS 主动创建，且尚未关闭。
如果你在 Apifox 或 wscat 里连的，DevTools 根本不会记录——它不监听系统级连接，只捕获本页 new WebSocket(...) 实例。
- 打开 DevTools → Network → 筛选
WS→ 找到目标连接 → 点击 → 切换到Messages子标签，才能看到收发帧时间线 - 如果
Messages标签灰掉或不存在，说明该连接已关闭，或压根没走标准 WebSocket 协议（比如用了 Socket.IO 封装层） - 想看握手头？切换到
Headers标签，重点查Sec-WebSocket-Accept是否匹配客户端Sec-WebSocket-Key的哈希结果 - 注意：Chrome 不显示二进制帧内容（
Binary类型），只标为(binary data)，调试二进制协议得换工具
Apifox 连接成功但收不到消息
Apifox 的 WebSocket 功能默认只监听文本帧（TEXT），如果服务端发的是二进制帧（BINARY），界面会静默丢弃，不报错也不提示。
另一个高频原因是：Apifox 不自动处理心跳，而服务端设置了 30 秒空闲超时，连接建好没发任何消息，30 秒后被单方面断开。
- 确认服务端发的是文本还是二进制——用
wscat或浏览器在线测试器复现，看能否收到 - 在 Apifox 的
Message输入框发一条空格或{"ping":true}触发一次交互，观察是否延缓断连 - 检查 Apifox 版本是否 ≥ 2.2.32，旧版对
Sec-WebSocket-Protocol支持有 Bug，会导致子协议协商失败后连接看似成功实则被服务端拒绝通信 - 若使用
Socket.IO协议，别用 Apifox 的原生 WebSocket 模块——它不兼容 IO 的握手和封包格式，得切到 Apipost 或专用 IO 调试器
1006 异常关闭，背后可能是 LB 空闲超时、TLS 握手失败、甚至 DNS 缓存未刷新。工具只告诉你“断了”，但不会告诉你“为什么断”。 
