WebSocket需服务端支持，前端仅发起连接；必须监听open/message/error/close事件，发送前检查readyState，二进制数据需设置binaryType，调试须用网络面板验证帧。

HTML5 的 WebSocket 不是“教程式配置”，而是客户端主动发起连接、服务端必须配套支持的双向通信机制。没有服务端（比如 Node.js 的 ws 库、Python 的 websockets、或 Nginx 反向代理配置），只写前端代码永远连不上。

WebSocket 连接前必须确认服务端已就绪

浏览器里直接 new WebSocket('ws://localhost:8080') 会立刻报错 WebSocket connection to 'ws://...' failed，这不是前端写错了，而是：服务端没运行、地址/端口不对、协议不匹配（ws:// vs wss://）、或被跨域/CORS 拦截（注意：WebSocket 不走 HTTP CORS，但服务端仍需显式允许来源）。

• 本地测试推荐用 npx wscat -l 8080（安装 wscat 后）快速起一个调试服务端
• 生产环境必须用 wss://，且证书有效；用 ws:// 在 HTTPS 页面中会被浏览器直接阻止
• 若服务端在内网或 Docker 中，确保端口已暴露、防火墙放行、客户端能 ping 通

创建实例后要监听 open/message/error/close 四个关键事件

WebSocket 是事件驱动的，不监听 open 就发消息，大概率触发 InvalidStateError: Failed to execute 'send' on 'WebSocket': Still in CONNECTING state；不处理 error 或 close，连接异常时页面就静默断连了。

const ws = new WebSocket('wss://api.example.com/ws');

ws.addEventListener('open', () => {
  console.log('已连接');
  ws.send(JSON.stringify({ type: 'auth', token: 'xxx' }));
});

ws.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('收到:', data);
});

ws.addEventListener('error', (err) => {
  console.error('WebSocket 错误:', err);
});

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

发送消息前务必检查 ws.readyState

即使监听了 open，在复杂交互中（比如重连逻辑、快速开关）仍可能因时序问题导致 send() 调用时状态不是 WebSocket.OPEN（值为 1）。硬编码发消息不加判断，就会报错。

• 安全写法：if (ws.readyState === WebSocket.OPEN) { ws.send(msg); }
• 避免在 open 回调外直接调用 send()，尤其不要在用户点击按钮时无条件发
• 如果需要重连，不要反复 new WebSocket，应封装状态管理，比如用 ReconnectingWebSocket 类库

接收消息时注意 event.data 类型不固定

event.data 可能是 String、Blob 或 ArrayBuffer，取决于服务端发的内容类型和浏览器设置。默认是字符串，但如果服务端发的是二进制（如图片帧、protobuf），前端没指定 binaryType 就会收不到预期数据。

• 明确服务端发什么：文本就保持默认；二进制需提前设 ws.binaryType = 'arraybuffer' 或 'blob'
• 不要直接对 event.data 调用 .json() 或 .text() —— 这些是 fetch 的方法，WebSocket 没有
• 解析 JSON 前先 typeof event.data === 'string' 判断，避免 JSON.parse(null) 报错

真正卡住人的从来不是怎么写 new WebSocket()，而是服务端没跑、协议写错、没处理断线、或把 event.data 当成 Response 对象来用。每一步都得对着网络面板里的 WS 标签看实际帧，而不是只盯控制台有没有 log。