能力中的 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>。
启动本地 WebSocket 与轮询端点
链接到“启动本地 WebSocket 与轮询端点”一节新建空目录,在其中运行 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。下文提到的客户端输出均为示意结果。
收发 JSON 并报告连接失败
链接到“收发 JSON 并报告连接失败”一节先注册处理函数,等 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 兼容性记录。
更正(2026-11-17)
链接到“更正(2026-11-17)”一节此次更正使 send() 与 bufferedAmount 的说明和标准保持一致。关闭握手开始后,浏览器不再传输交给 send() 的数据;只要调用没有抛出异常,bufferedAmount 仍会按数据字节数增加,连接关闭后的调用也不例外(WebSockets Standard,send(),WHATWG;WebSockets Standard,bufferedAmount,WHATWG)。原 publishedAt 日期保持不变。
另请参阅
链接到“另请参阅”一节- WebTransport API,通过 HTTP/3 使用流与数据报
- Web Locks API,协调由哪个同源标签页持有连接
- WebSockets Standard(WHATWG)
- RFC 6455: The WebSocket Protocol(IETF)
- RFC 7692: Compression Extensions for WebSocket(IETF)
- Network features reference(Chrome for Developers)
规范
| 规范 | 状态 |
|---|---|
| WebSockets Standard: The WebSocket interface | WHATWG 现行标准 |
| RFC 6455: The WebSocket Protocol | 其他 |
| RFC 7692: Compression Extensions for WebSocket | 其他 |