WebSocket 核心 API 速查表
本速查表基于 WebSocket 协议规范及前端实践场景整理，涵盖核心对象属性、方法、事件回调及错误处理方案，适用于日常开发查阅。
一、WebSocket 核心对象与初始化
1. 核心对象
WebSocket：浏览器内置构造函数，用于创建 WebSocket 连接实例，是所有操作的基础。
2. 初始化语法
// 基础语法：ws（非加密）或 wss（加密，类似 HTTPS）
const socket = new WebSocket('ws://example.com');
// 加密连接示例（生产环境推荐）
const secureSocket = new WebSocket('wss://example.com');
- 参数说明：URL 必须以
ws://或wss://开头，指向支持 WebSocket 协议的服务器地址。
二、WebSocket 核心属性
| 属性名 | 类型 | 说明 |
|---|---|---|
readyState | 数字 | 连接状态码： 0 - CONNECTING（连接中） 1 - OPEN（连接已打开） 2 - CLOSING（关闭中） 3 - CLOSED（已关闭） |
bufferedAmount | 数字 | 已发送但未被服务器确认的字节数，用于判断发送缓冲区是否已满 |
protocol | 字符串 | 实际使用的子协议（若初始化时指定多个协议，返回服务器选中的协议） |
url | 字符串 | 创建连接时使用的 URL（只读） |
三、WebSocket 核心方法
| 方法名 | 语法 | 说明 |
|---|---|---|
send() | socket.send(data) | 向服务器发送数据，data 支持字符串、Blob、ArrayBuffer 类型；注意：连接未打开（ readyState!==1）时调用会报错 |
close() | socket.close(code, reason) | 主动关闭连接；code（可选）：关闭状态码（默认 1005，代表无状态码）；reason（可选）：字符串，描述关闭原因 |
四、WebSocket 核心事件回调
WebSocket 通过“事件驱动”处理连接生命周期，需通过绑定回调函数响应各类状态变化。
| 事件名 | 绑定方式 | 触发场景 |
|---|---|---|
open | socket.onopen = () => {} | 连接成功建立时触发（readyState 变为 1） |
message | socket.onmessage = (event) => {} | 收到服务器发送的数据时触发； 通过 event.data 获取数据（自动解析为字符串/Blob） |
error | socket.onerror = (error) => {} | 连接发生错误时触发（如握手失败、网络中断）； 注意：错误后连接可能自动关闭 |
close | socket.onclose = (event) => {} | 连接关闭时触发（主动关闭或被动关闭）； 通过 event.code 获取关闭状态码，event.reason 获取关闭原因 |
五、常见错误与解决方案
| 错误类型 | 可能原因 | 解决方案 |
|---|---|---|
| 浏览器不支持 WebSocket | 使用 IE8 及以下等旧浏览器 | 检测 typeof WebSocket !== 'function'，提示用户更换 Chrome/Firefox 等现代浏览器 |
| 握手失败（handshake error） | URL 格式错误、服务器未支持 WebSocket | 1. 检查 URL 前缀是否为 ws:///wss://；2. 确认服务器已开启 WebSocket 服务 |
| 连接意外关闭（connection closed） | 网络波动、服务器重启、长时间无数据传输 | 在 onclose 中添加重连逻辑（排除主动关闭场景），结合心跳机制维持连接 |
| 发送数据失败 | 连接未打开（readyState!==1）、数据格式错误 | 1. 发送前检查 readyState；2. 确保数据为字符串/Blob/ArrayBuffer 类型 |
| 连接超时（timeout） | 网络延迟高、服务器超时策略 | 实现 Ping/Pong 心跳机制（每 30s 发送 Ping 帧），避免连接被服务器主动断开 |
六、关键状态码说明
WebSocket 定义了标准化状态码，用于标识连接关闭原因，开发中可通过 event.code 获取：
| 状态码 | 含义 | 场景示例 |
|---|---|---|
| 1000 | 正常关闭 | 客户端/服务器主动调用 close() 关闭连接 |
| 1001 | 端点离开 | 客户端页面关闭、服务器下线 |
| 1002 | 协议错误 | 数据格式不符合 WebSocket 协议规范 |
| 1003 | 不支持的数据类型 | 发送服务器不支持的数据格式（如二进制数据） |
| 1005 | 无状态码 | 关闭时未指定状态码（默认值） |
| 1006 | 异常关闭 | 网络中断、连接意外断开（无明确原因） |
七、实战常用工具函数
1. 连接状态检测
// 检查连接是否可发送数据
function isSocketAvailable(socket) {return socket && socket.readyState === WebSocket.OPEN;
}
2. 安全发送数据
// 确保连接打开后再发送数据
function safeSend(socket, data) {if (isSocketAvailable(socket)) {socket.send(typeof data === 'object' ? JSON.stringify(data) : data);} else {console.error('WebSocket 连接未打开，发送失败');}
}
3. 心跳机制实现
// 为 socket 添加心跳（每 30s 发送 Ping，5s 未响应则重连）
function addHeartbeat(socket, reconnectFn) {let heartbeatTimer;let checkTimer;// 发送心跳function sendPing() {if (isSocketAvailable(socket)) {socket.send(JSON.stringify({ type: 'ping' }));// 等待 Pong 响应checkTimer = setTimeout(() => {socket.close(1006, '心跳无响应');reconnectFn(); // 重连函数}, 5000);}}// 启动心跳heartbeatTimer = setInterval(sendPing, 30000);// 收到 Pong 时清除检查计时器socket.onmessage = (event) => {const data = JSON.parse(event.data);if (data.type === 'pong') {clearTimeout(checkTimer);}};// 关闭时清除计时器socket.onclose = () => {clearInterval(heartbeatTimer);clearTimeout(checkTimer);};
}