跳转到内容

能力中的 API

WebSocket API

发布于 更新于

WebSocket 在浏览器和服务器之间建立双向连接,再用事件向脚本交付文本或二进制消息。标准可能在开启握手期间或之后因协议层或 API 层原因判定 WebSocket 连接失败;判定连接失败会关闭连接并触发 error 和 close 事件(WebSockets Standard,WHATWG)。

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,WHATWG)。

send() 接受字符串、Blob、ArrayBuffer 或 ArrayBufferView。若希望收到的二进制消息采用 ArrayBuffer,把 binaryType 设为 "arraybuffer";默认值为 "blob"。脚本不能通过这套 API 直接收发协议层 Ping 和 Pong 帧。RFC 6455 定义了这两类控制帧,并允许连接任一端发送(RFC 6455 第 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,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,WHATWG;WebSockets Standard,send(),WHATWG)。

RFC 7692 定义了压缩 WebSocket 消息载荷的 permessage-deflate 扩展。浏览器与服务器在开启握手期间协商扩展;请从 extensions 读取结果,不要假定已经启用压缩(RFC 7692,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(),WHATWG;WebSockets Standard,bufferedAmount,WHATWG)。若连接消失前没有收到 Close 帧,RFC 6455 把关闭代码定义为 1006;该值属于保留代码,不能传给 close()(RFC 6455 第 7.1.5 与 7.4.1 节,IETF)。

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

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

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。下文提到的客户端输出均为示意结果。

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

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,当浏览器中的应用数据队列超过自定上限时暂停添加数据。下面的上限属于示例策略,不是协议常量。

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 轮询接口。服务器必须实现该接口,回退才能工作。

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(),WHATWG)。若要和支持流及数据报的另一种传输方式比较,可查阅 WebTransport 兼容性记录。

此次更正使 send() 与 bufferedAmount 的说明和标准保持一致。关闭握手开始后,浏览器不再传输交给 send() 的数据;只要调用没有抛出异常,bufferedAmount 仍会按数据字节数增加,连接关闭后的调用也不例外(WebSockets Standard,send(),WHATWG;WebSockets Standard,bufferedAmount,WHATWG)。原 publishedAt 日期保持不变。

规范

规范状态
WebSockets Standard: The WebSocket interfaceWHATWG 现行标准
RFC 6455: The WebSocket Protocol其他
RFC 7692: Compression Extensions for WebSocket其他