WebSockets

WebSockets 允许您与 Cloudflare Workers 无服务器函数进行实时通信。完整示例请参阅使用 WebSockets API。

// { 0: <WebSocket>, 1: <WebSocket> }
let websocketPair = new WebSocketPair();

此构造函数返回的 WebSocketPair 是一个 Object，在键 0 和 1 处各有一个 WebSocket。

这些 WebSocket 通常称为 client 和 server。以下示例结合 Object.values 和 ES6 解构，将 WebSocket 检索为 client 和 server：

let [client, server] = Object.values(new WebSocketPair());

• accept(options?)
  • 接受 WebSocket 连接，并开始在 Cloudflare 全球网络上终止 WebSocket 请求。这有效地使 Workers 运行时能够开始响应和处理 WebSocket 请求。

• options object optional

  • 可选配置对象，包含以下属性：

    • allowHalfOpen boolean optional — 当为 true 时，运行时不会在从对等方收到 Close 帧时自动发送对应的 Close 帧。相反，readyState 保持 CLOSING 状态，直到您显式调用 close()。这对于需要协调代理两侧关闭的 WebSocket 代理 很有用。默认为 false。

• addEventListener(eventWebSocketEvent, callbackFunctionFunction)
  • 添加在 WebSocket 上发生事件时要执行的回调函数。

• event WebSocketEvent

  • 要监听的 WebSocket 事件（请参阅事件）。

• callbackFunction(messageMessage) Function

  • WebSocket 响应特定事件时要调用的函数。

• close(codenumber, reasonstring)
  • 关闭 WebSocket 连接。

• codeinteger optional

  • 表示服务器发送的关闭代码的整数。应与 WebSocket 规范提供的状态码列表 ↗中的选项匹配。

• reasonstring optional

  • 表示 WebSocket 连接关闭原因的可读字符串。

• send(messagestring | ArrayBuffer | ArrayBufferView)
  • 向此 WebSocket 对中的另一个 WebSocket 发送消息。

• messagestring
  • 要通过 WebSocket 连接发送给对应客户端的消息。应为字符串或可强制转换为字符串的值；例如，字符串和数字会被直接转换为字符串，但对象和数组应使用 JSON.stringify 转换为 JSON 字符串，并在客户端解析。

• readyState number

  • 返回 WebSocket 连接的当前状态。可能的值：

    Constant	Value	Description
    WebSocket.CONNECTING	0	连接尚未打开。
    WebSocket.OPEN	1	连接已打开，可以通信。
    WebSocket.CLOSING	2	连接正在关闭。
    WebSocket.CLOSED	3	连接已关闭。

• binaryType string

  • 控制此 WebSocket 上接收的二进制帧如何呈现给 message 事件。有效值为 "blob" 和 "arraybuffer"。每次分发传入的二进制帧时都会查询该值，因此分配新值仅影响后续消息。默认值由 websocket_standard_binary_type 兼容性标志控制。有关详细信息，请参阅二进制消息。

• close
  • 表示 WebSocket 已关闭的事件。CloseEvent 包含 code（number）、reason（string）和 wasClean（boolean）属性。
• error
  • 表示 WebSocket 发生错误的事件。
• message
  • 表示从客户端收到新消息的事件，包括客户端传递的数据。

• data any - 从 WebSocket 对中的另一个 WebSocket 传回的数据。
• type string - 默认为 message。

使用 web_socket_auto_reply_to_close 兼容性标志（在 2026-04-07 及之后的兼容性日期上默认启用）时，Workers 运行时在收到来自对等方的 Close 帧时会自动发送对应的 Close 帧。readyState 在 close 事件触发之前过渡到 CLOSED。这与 WebSocket 规范 ↗ 和标准浏览器行为一致。

如果您仍在 close 事件处理程序中调用 close()，该调用会被静默忽略。手动回复 Close 帧的现有代码无需更改即可继续工作。

server.addEventListener("close", (event) => {
  // readyState is already CLOSED — no need to call server.close().
  console.log(server.readyState); // WebSocket.CLOSED
  console.log(event.code);        // 1000
  console.log(event.wasClean);    // true
});

自动关闭行为可能会干扰 WebSocket 代理，其中 Worker 位于客户端和后端之间，需要独立协调两侧的关闭。要支持此场景，请向 accept() 传递 { allowHalfOpen: true }：

server.accept({ allowHalfOpen: true });

server.addEventListener("close", (event) => {
  // readyState is still CLOSING here, giving you time
  // to coordinate the close on the other side.
  console.log(server.readyState); // WebSocket.CLOSING

  // Manually close when ready.
  server.close(event.code, "done");
});

在 2026-04-07 之前的兼容性日期（或使用 web_socket_manual_reply_to_close 标志）上，收到 Close 帧会使 WebSocket 处于 CLOSING 状态，您的代码必须调用 close() 来完成握手。否则可能导致客户端出现 1006 异常关闭错误。

WebSocket 帧携带文本或二进制负载，两者之间的选择由发送方在发送帧时做出。文本帧始终以 JavaScript 字符串形式传递给 message 事件。二进制帧根据 WebSocket 的 binaryType 以 Blob ↗ 或 ArrayBuffer ↗ 形式传递。

使用 websocket_standard_binary_type 兼容性标志（在 2026-03-17 及之后的兼容性日期上默认启用）时，binaryType 默认为 "blob"，二进制帧以 Blob 对象传递。这与 WebSocket 规范 ↗ 和标准浏览器行为一致。没有此标志时，binaryType 默认为 "arraybuffer"，二进制帧以 ArrayBuffer 传递，与运行时的历史行为一致。

binaryType 属性本身始终可用。要为单个 WebSocket 选择 ArrayBuffer 传递，请在调用 accept() 之前分配 binaryType：

const resp = await fetch("https://example.com", {
  headers: { Upgrade: "websocket" },
});
const ws = resp.webSocket;

// Opt back into ArrayBuffer delivery for this WebSocket.
ws.binaryType = "arraybuffer";
ws.accept();

ws.addEventListener("message", (event) => {
  if (typeof event.data === "string") {
    // Text frame.
  } else {
    // event.data is an ArrayBuffer because we set binaryType above.
  }
});

无论 binaryType 如何，传入的二进制帧在 message 事件触发之前都会被完全缓冲。Blob 和 ArrayBuffer 之间的选择不会改变帧接收的时间或是否接收 — 仅改变您访问其字节的方式：

• 使用 "arraybuffer" 时，event.data 是 ArrayBuffer ↗。您可以同步检查其大小并读取字节（例如 new Uint8Array(event.data)）。
• 使用 "blob" 时，event.data 是 Blob ↗。读取字节是异步的 — 例如 await event.data.arrayBuffer() 或 await event.data.bytes()。

在新默认值下，二进制消息处理程序必须是 async 才能读取负载。如果您想保留现有的同步处理程序，请在 WebSocket 上将 binaryType 设置为 "arraybuffer"。

根据 WebSocket 规范 ↗，binaryType 是可变的：每次将二进制帧分派到 message 事件时都会查询该值，因此分配新值仅影响后续消息。如果您希望 WebSocket 上的每个二进制消息都以相同类型传递，请在调用 accept() 之前分配 binaryType。这可以确保在运行时尚未开始分派任何传入帧之前，设置已就位。

如果您尚未准备好迁移，并希望 Worker 中的每个 WebSocket 都默认使用 ArrayBuffer，请将 no_websocket_standard_binary_type 标志添加到 Wrangler 配置文件。单个 WebSocket 仍可通过分配 binaryType 覆盖默认值。

• Mozilla Developer Network (MDN) 上的 WebSocket 类文档 ↗
• 在 Workers 上使用 WebSockets 构建应用的 WebSocket 模板 ↗