# WebSocket API

> WebSocket 建立持久的客户端与服务器连接；本参考涵盖构造、消息收发、发送队列限制、关闭处理和轮询回退。

`WebSocket` 在浏览器和服务器之间建立双向连接，再用事件向脚本交付文本或二进制消息。标准可能在开启握手期间或之后因协议层或 API 层原因判定 WebSocket 连接失败；判定连接失败会关闭连接并触发 `error` 和 `close` 事件（[WebSockets Standard](https://websockets.spec.whatwg.org/)，WHATWG）。

## 语法

```js
const socket = new WebSocket(url)
const socket = new WebSocket(url, protocol)
const socket = new WebSocket(url, protocols)

socket.send(data)
socket.close()
socket.close(code)
socket.close(code, reason)
```

构造函数接受绝对或相对的 `ws`、`wss`、`http`、`https` URL。标准要求把 `http` 改成 `ws`、把 `https` 改成 `wss`，拒绝含片段的 URL，并用相关设置对象的 API 基础 URL 解析相对地址。第二个参数可传一个子协议字符串或一组子协议字符串。服务器可以不选择子协议而建立连接，此时 `protocol` 为空字符串。服务器若选择子协议，该值必须来自客户端的提议；握手完成后，`protocol` 返回选中值（[WebSockets Standard: opening handshake](https://websockets.spec.whatwg.org/#opening-handshake)，WHATWG）。

`send()` 接受字符串、`Blob`、`ArrayBuffer` 或 `ArrayBufferView`。若希望收到的二进制消息采用 `ArrayBuffer`，把 `binaryType` 设为 `"arraybuffer"`；默认值为 `"blob"`。脚本不能通过这套 API 直接收发协议层 Ping 和 Pong 帧。RFC 6455 定义了这两类控制帧，并允许连接任一端发送（[RFC 6455 第 5.5 节](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5)，IETF）。

## 浏览器支持

BCD `api.WebSocket` 记录的接口支持起点包括 Chrome 5、Edge 12、无前缀的 Firefox 11、IE 10、Opera 12.1、Safari 5 和 Opera Android 12.1。这条记录中，Chrome Android、Firefox for Android、Oculus Browser、Safari on iOS、Samsung Internet、WebView Android 和 WebView on iOS 使用镜像项。`api.WebSocket.WebSocket.url_parameter_http_https_relative` 记录了构造函数接受 `http`、`https` 与相对 URL 的支持起点：Chrome 125、Firefox 124 和 Safari 17.3。Chrome Android、Edge、Firefox for Android、Oculus Browser、Opera、Opera Android、Safari on iOS、Samsung Internet、WebView Android 和 WebView on iOS 在这项行为下使用镜像记录（[WebSocket.json](https://github.com/mdn/browser-compat-data/blob/main/api/WebSocket.json)，MDN browser-compat-data）。

## 成员

| 成员 | 类型 | 含义 |
|---|---|---|
| `url` | `USVString` | 建立连接时使用的 URL。 |
| `readyState` | `unsigned short` | `CONNECTING`（0）、`OPEN`（1）、`CLOSING`（2）或 `CLOSED`（3）。 |
| `bufferedAmount` | `unsigned long long` | 脚本经 `send()` 排队、但尚未传到网络的应用数据字节数。 |
| `extensions` | `DOMString` | 服务器选中的扩展；尚未选定时为空字符串。 |
| `protocol` | `DOMString` | 服务器选中的子协议；未选中时为空字符串。 |
| `binaryType` | `BinaryType` | `"blob"` 或 `"arraybuffer"`，初始值为 `"blob"`。 |
| `open` | `Event` | 连接建立且 `readyState` 变为 `OPEN` 后触发。 |
| `message` | `MessageEvent` | 在 `data` 中携带一条完整的文本或二进制消息。 |
| `error` | `Event` | 连接失败时触发。 |
| `close` | `CloseEvent` | 提供 `code`、`reason` 以及连接是否干净关闭。 |

`bufferedAmount` 计算脚本排队的 UTF-8 文本和二进制字节，不包括 WebSocket 帧开销、操作系统缓冲区与网络硬件缓冲区。除 `CONNECTING` 状态抛出异常的情况外，每次 `send()` 调用都会按所给数据的字节数增加 `bufferedAmount`。

关闭握手已经开始或连接已经关闭时，浏览器不会传输这些数据，但 `bufferedAmount` 仍会增加，连接关闭后也不会归零。发送前应同时检查 `readyState` 和应用自己的队列上限（[WebSockets Standard，`bufferedAmount`](https://websockets.spec.whatwg.org/#dom-websocket-bufferedamount)，WHATWG；[WebSockets Standard，`send()`](https://websockets.spec.whatwg.org/#dom-websocket-send)，WHATWG）。

RFC 7692 定义了压缩 WebSocket 消息载荷的 `permessage-deflate` 扩展。浏览器与服务器在开启握手期间协商扩展；请从 `extensions` 读取结果，不要假定已经启用压缩（[RFC 7692](https://datatracker.ietf.org/doc/html/rfc7692)，IETF）。

## 异常

| 异常或事件 | 触发条件 |
|---|---|
| `SyntaxError` | 构造函数无法解析 URL、解析后的方案不是 `ws` 或 `wss`、URL 含片段，或子协议重复或不合法。 |
| `InvalidStateError` | `readyState` 仍为 `CONNECTING` 时调用 `send()`。 |
| `SyntaxError` | `close()` 的理由经 UTF-8 编码后超过 123 字节。 |
| `InvalidAccessError` | `close()` 的代码既不是 `1000`，也不在整数 `3000` 至 `4999` 之间。 |
| `error` 后接 `close` | 建立连接失败；标准的失败路径会关闭连接并触发 `close`。 |

`readyState` 为 `CLOSING` 或 `CLOSED` 时调用 `send()`，标准要求丢弃数据，不再传输。只要调用没有抛出异常，`bufferedAmount` 仍会按数据字节数增加；连接关闭后的后续 `send()` 调用也会继续增加这个值（[WebSockets Standard，`send()`](https://websockets.spec.whatwg.org/#dom-websocket-send)，WHATWG；[WebSockets Standard，`bufferedAmount`](https://websockets.spec.whatwg.org/#dom-websocket-bufferedamount)，WHATWG）。若连接消失前没有收到 Close 帧，RFC 6455 把关闭代码定义为 `1006`；该值属于保留代码，不能传给 `close()`（[RFC 6455 第 7.1.5 与 7.4.1 节](https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.5)，IETF）。

:::caution
Chrome DevTools 把 WebSocket 检查视图标为 **Messages**，厂商文档说明表格显示最后 100 条消息。应用收到意外载荷或关闭时，在 **Network** 中选中连接，打开 **Messages**，再检查 **Data**、**Length** 与 **Time**（[Network features reference](https://developer.chrome.com/docs/devtools/network/reference/#websocket)，Chrome for Developers）。这个视图只用于诊断，不是完整的连接日志。
:::

## 示例

先启动下方的本地端点，再运行浏览器示例。它会在 `http://localhost:8080` 提供页面、从 `/socket` 回显 WebSocket 消息，并实现轮询所需的 `GET /api/updates?since=<cursor>`。

### 启动本地 WebSocket 与轮询端点

新建空目录，在其中运行 `npm init -y` 和 `npm install ws`，再把以下代码保存为 `server.mjs`。运行 `node server.mjs` 后，用浏览器打开 `http://localhost:8080`。

```js
import { createServer } from "node:http";
import { WebSocketServer } from "ws";

const server = createServer((request, response) => {
  const url = new URL(request.url, "http://localhost:8080");
  if (url.pathname === "/api/updates") {
    const previous = Number.parseInt(url.searchParams.get("since") || "0", 10);
    const cursor = String(Number.isFinite(previous) ? previous + 1 : 1);
    response.writeHead(200, { "content-type": "application/json" });
    response.end(JSON.stringify({ cursor, items: [{ type: "update", value: cursor }] }));
    return;
  }

  response.writeHead(200, { "content-type": "text/html" });
  response.end("<!doctype html><title>WebSocket demo</title><p>Open DevTools.</p>");
});

const sockets = new WebSocketServer({ noServer: true });

server.on("upgrade", (request, socket, head) => {
  const url = new URL(request.url, "http://localhost:8080");
  if (url.pathname !== "/socket") {
    socket.destroy();
    return;
  }
  sockets.handleUpgrade(request, socket, head, (webSocket) => {
    sockets.emit("connection", webSocket, request);
  });
});

sockets.on("connection", (socket) => {
  socket.on("message", (data) => socket.send(data.toString()));
});

server.listen(8080, () => console.log("Listening on http://localhost:8080"));
```

终端会打印 `Listening on http://localhost:8080`。浏览器页面与轮询接口同源，因此回退示例可以使用相对 URL。下文提到的客户端输出均为示意结果。

### 收发 JSON 并报告连接失败

先注册处理函数，等 `open` 后再发送。使用消息正文前先校验 JSON；无效消息与连接关闭都要显示给用户。

```js
function connectChat(url, render, report) {
  const socket = new WebSocket(url, "chat.v1");

  socket.addEventListener("open", () => {
    socket.send(JSON.stringify({ type: "hello", value: "browser" }));
  });

  socket.addEventListener("message", (event) => {
    let message;
    try {
      message = JSON.parse(event.data);
    } catch (error) {
      report(`Invalid JSON: ${error.message}`);
      socket.close(1000, "invalid payload");
      return;
    }
    render(message);
  });

  socket.addEventListener("error", () => report("WebSocket connection failed"));
  socket.addEventListener("close", (event) => {
    report(`Closed with code ${event.code}; clean=${event.wasClean}`);
  });

  return socket;
}

const socket = connectChat(
  "ws://localhost:8080/socket",
  (message) => console.log("message", message),
  (status) => console.log("status", status),
);
```

接入符合上述回显约定的端点后，控制台先打印返回对象。无效 JSON 会打印 `Invalid JSON:`，再以代码 `1000` 发起正常关闭。握手失败会进入 `error` 与 `close` 处理函数；WebSocket API 的 `error` 事件本身不提供 HTTP 响应状态。

### 限制应用队列

生产者可查看 `bufferedAmount`，当浏览器中的应用数据队列超过自定上限时暂停添加数据。下面的上限属于示例策略，不是协议常量。

```js
const MAX_QUEUED_BYTES = 256 * 1024;

function sendSample(socket, sample, onDeferred) {
  if (socket.readyState !== WebSocket.OPEN) {
    onDeferred(sample, "socket is not open");
    return false;
  }

  const payload = JSON.stringify(sample);
  const bytes = new TextEncoder().encode(payload).byteLength;
  if (socket.bufferedAmount + bytes > MAX_QUEUED_BYTES) {
    onDeferred(sample, "application queue limit reached");
    return false;
  }

  socket.send(payload);
  return true;
}

const accepted = sendSample(
  socket,
  { type: "cursor", x: 12, y: 30 },
  (sample, reason) => console.log("deferred", reason, sample),
);
console.log("accepted", accepted);
```

套接字未打开或本地队列超过选定上限时，函数不会调用 `send()`，并返回 `false`。应用可按自身交付规则保留或替换延迟样本；`bufferedAmount` 只报告排队字节数，不制定处理策略。

### 检测支持并切换到轮询

构造前先检测全局对象。若浏览器没有 WebSocket，或套接字未能打开，就停用这条路径并请求约定的 HTTP 轮询接口。服务器必须实现该接口，回退才能工作。

```js
async function startPolling(render, signal) {
  let cursor = "";
  while (!signal.aborted) {
    const url = `/api/updates?since=${encodeURIComponent(cursor)}`;
    const response = await fetch(url, { signal });
    if (!response.ok) throw new Error(`Polling failed: HTTP ${response.status}`);
    const batch = await response.json();
    batch.items.forEach(render);
    cursor = batch.cursor;
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

function subscribe(render) {
  const controller = new AbortController();
  if (!('WebSocket' in window)) {
    startPolling(render, controller.signal).catch(console.error);
    return () => controller.abort();
  }

  const socket = new WebSocket("ws://localhost:8080/socket");
  let opened = false;
  socket.addEventListener("open", () => { opened = true; });
  socket.addEventListener("message", (event) => render(JSON.parse(event.data)));
  socket.addEventListener("close", () => {
    if (!opened) startPolling(render, controller.signal).catch(console.error);
  }, { once: true });

  return () => {
    controller.abort();
    if (socket.readyState === WebSocket.CONNECTING ||
        socket.readyState === WebSocket.OPEN) {
      socket.close(1000, "subscription stopped");
    }
  };
}
```

浏览器没有 `WebSocket` 时，第一个请求会发往 `/api/updates?since=`，本地服务器返回的首项 `value` 为 `"1"`。构造函数存在但开启握手失败时，`close` 处理函数会启动同一路由。调用返回的清理函数会中止轮询。套接字处于 `OPEN` 时，清理会发起 WebSocket 关闭握手；处于 `CONNECTING` 时，清理会让连接失败；处于 `CLOSING` 或 `CLOSED` 时，代码不会再次调用 `close()`（[WebSockets Standard: `close()`](https://websockets.spec.whatwg.org/#dom-websocket-close)，WHATWG）。若要和支持流及数据报的另一种传输方式比较，可查阅 [WebTransport 兼容性记录](/zh/compatibility/webtransport/)。

## 更正（2026-11-17）

此次更正使 `send()` 与 `bufferedAmount` 的说明和标准保持一致。关闭握手开始后，浏览器不再传输交给 `send()` 的数据；只要调用没有抛出异常，`bufferedAmount` 仍会按数据字节数增加，连接关闭后的调用也不例外（[WebSockets Standard，`send()`](https://websockets.spec.whatwg.org/#dom-websocket-send)，WHATWG；[WebSockets Standard，`bufferedAmount`](https://websockets.spec.whatwg.org/#dom-websocket-bufferedamount)，WHATWG）。原 `publishedAt` 日期保持不变。

## 另请参阅

- [WebTransport API](/zh/reference/capabilities/webtransport/)，通过 HTTP/3 使用流与数据报
- [Web Locks API](/zh/reference/capabilities/web-locks/)，协调由哪个同源标签页持有连接
- [WebSockets Standard](https://websockets.spec.whatwg.org/)（WHATWG）
- [RFC 6455: The WebSocket Protocol](https://datatracker.ietf.org/doc/html/rfc6455)（IETF）
- [RFC 7692: Compression Extensions for WebSocket](https://datatracker.ietf.org/doc/html/rfc7692)（IETF）
- [Network features reference](https://developer.chrome.com/docs/devtools/network/reference/#websocket)（Chrome for Developers）