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）。硬编码发消息不加判断，就会报错。
诊断并恢复通过 SSH 隧道连接的 OpenClaw 节点。用于解决配对必需错误、隧道冲突、远程端点错误以及 SSH 目标配置错误等问题。
立即学习“前端免费学习笔记（深入）”；
- 安全写法：
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。
