WebSocket连接失败主因是服务端未启动、端口被占或协议/跨域不匹配；需显式指定ws://或wss://完整URL，手动绑定onopen/onmessage/onerror/onclose事件，并实现超时检测与心跳保活。
WebSocket 连接失败的常见错误信息
看到 WebSocket connection to 'ws://...' failed 或 net::ERR_CONNECTION_REFUSED，基本说明客户端没连上服务端。不是前端代码写错了，而是服务端根本没启动、端口被占、或跨域/协议不匹配（比如用 ws:// 连 https:// 页面但后端只监听 http://）。Chrome 控制台 Network 标签页里看不到 WebSocket 握手请求（Upgrade: websocket），就说明连接压根没发出去。
new WebSocket() 的 URL 必须带协议和端口
不能只写 new WebSocket('localhost:8080')，必须显式指定协议和完整地址：
const ws = new WebSocket('ws://localhost:8080'); // HTTP 页面用 ws://
// 或
const ws = new WebSocket('wss://example.com'); // HTTPS 页面必须用 wss://
漏掉 ws:// 前缀会导致浏览器当作相对路径解析，最终请求一个不存在的 HTTP 接口，报 404 或直接静默失败。本地开发时如果后端跑在 http://localhost:3000，前端也得确保是同源或后端已配好 CORS（虽然 WebSocket 不走 CORS 检查，但页面加载来源会影响协议匹配）。
onopen / onmessage / onerror / onclose 四个事件必须手动绑定
WebSocket 是事件驱动的，没有自动重连、没有内置心跳，所有逻辑都要自己写。容易忽略的是 onerror —— 它不抛异常，也不终止连接，只是告诉你出错了，但连接状态可能已是 CLOSED；而 onclose 触发时，event.code 和 event.reason 才能帮你判断是服务端主动断开（如 code=1001），还是网络中断（code=1006）。
立即学习“前端免费学习笔记（深入）”；
-
onopen：只在握手成功后触发一次，适合发初始化消息 -
onmessage：收到字符串或Blob，需用event.data instanceof Blob判断是否要调event.data.text() -
onerror：仅表示某次操作失败（如 send 失败），不代表连接已断，别在这里直接ws.close() -
onclose：连接真正关闭，此时ws.readyState === 0（CONNECTING）或3（CLOSED）
服务端没运行或端口不通时，前端不会报错提示你
WebSocket 的 onerror 在连接阶段往往不触发，onclose 也可能延迟几秒才来，甚至不触发（取决于 TCP 层超时）。最稳妥的做法是加一个连接超时检测：
const ws = new WebSocket('ws://localhost:8080');
let timeoutId = setTimeout(() => {
if (ws.readyState === WebSocket.CONNECTING) {
ws.close();
console.error('WebSocket connection timeout');
}
}, 5000);
ws.onopen = () => clearTimeout(timeoutId);
ws.onclose = () => clearTimeout(timeoutId);
ws.onerror = () => clearTimeout(timeoutId);
真实项目里，这个超时逻辑常被封装进连接管理器，否则用户点开页面干等 10 秒没反应，根本不知道是后端挂了还是网络坏了。
WebSocket 的难点不在语法，而在连接生命周期管理——它不像 HTTP 那样“请求-响应”即结束，而是一条长期存活的管道，任何一端掉线都不会自动通知另一端。服务端进程重启、Nginx 代理超时、移动网络切换，都可能导致连接静默失效。这些情况，光靠前端onclose 捕获不到。 
