WebSocket连接失败主因是环境或协议不匹配；需确认协议一致、服务端运行、升级处理正确、反向代理支持Upgrade头；须监听open/message/error/close事件；仅支持字符串和ArrayBuffer传输；需手动实现带退避的重连策略。
WebSocket连接失败的常见原因和快速排查
绝大多数 WebSocket 连接问题不是代码写错，而是环境或协议不匹配。浏览器控制台报 WebSocket connection to 'ws://...' failed 时，先确认这几点：
-
ws://或wss://必须与服务端协议严格一致；HTTP 站点不能直接连wss://（会因混合内容被浏览器拦截） - 服务端未启动，或监听地址/端口与前端
new WebSocket('ws://localhost:8080')不一致 - 服务端未正确处理 WebSocket 升级请求（如 Express 用原生
http.Server而非express()实例监听） - 反向代理（Nginx、Caddy）未配置 WebSocket 支持，缺少
Upgrade和Connection头转发
建立连接并处理生命周期事件
WebSocket 是事件驱动模型，必须显式监听 open、message、error、close 四个核心事件，否则收不到消息或无法感知断连。
const ws = new WebSocket('ws://localhost:3000');
ws.onopen = () => {
console.log('已连接');
ws.send(JSON.stringify({ type: 'auth', token: 'abc123' }));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('收到:', data);
};
ws.onerror = (err) => {
console.error('连接异常:', err);
};
ws.onclose = (e) => {
console.log(`断开连接，码 ${e.code}，原因 ${e.reason}`);
};
注意：onopen 触发后才能调用 send()；onmessage 的 event.data 是字符串或 Blob，需手动解析；onerror 不会携带具体错误信息，只表示连接过程出错，真正原因要查服务端日志或网络面板。
发送与接收数据的类型和边界
WebSocket 原生只支持字符串和 ArrayBuffer（含 Uint8Array），不支持直接传对象或 File。常见误操作：
立即学习“Java免费学习笔记（深入）”；
一套面向小企业用户的企业网站程序！功能简单，操作简单。实现了小企业网站的很多实用的功能，如文章新闻模块、图片展示、产品列表以及小型的下载功能，还同时增加了邮件订阅等相应模块。公告，友情链接等这些通用功能本程序也同样都集成了！同时本程序引入了模块功能，只要在系统默认模板上创建模块，可以在任何一个语言环境（或任意风格）的适当位置进行使用！
- 直接
ws.send({ id: 1 })→ 报错Failed to execute 'send' on 'WebSocket': Data must be a string or ArrayBuffer - 用
JSON.stringify()发送，但服务端未做JSON.parse()→ 数据变成纯字符串，逻辑解析失败 - 发送大文件时未分片，导致单帧超限（多数服务端默认限制 1MB）
推荐做法：统一用 JSON 字符串通信，业务层封装编解码逻辑；二进制数据（如图片、音频）走 ArrayBuffer，并约定好格式头（如前4字节为长度）。
自动重连与连接状态管理
WebSocket 断开后不会自动重连，必须手动实现。但不能无条件立即重试——网络抖动时频繁新建连接会加重服务端压力，也容易触发浏览器限制。
一个轻量可靠的重连策略：
- 记录当前连接状态（
ws.readyState：0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED） - 在
onclose中启动带退避的定时器（如 1s → 2s → 4s → 最大16s） - 每次重连前检查
ws.readyState === WebSocket.CLOSED，避免重复 new - 设置最大重试次数（如5次），失败后提示用户“网络异常，请刷新页面”
真实项目中，别依赖 setInterval 检查 readyState——它永远是 0 或 3，只有 onopen/onclose 才是唯一可信的状态入口。
