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);
  };
}