# @azure/web-pubsub-client 中文文档

规范地址：https://npmcn.com/package/%40azure/web-pubsub-client/

版本：1\.1\.0
npm 元数据更新时间：2026-06-29T03:13:17.440Z
中文译文更新时间：2026-11-07T13:21:22.547Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/web-pubsub-client
原文对照：https://npmcn.com/package/%40azure/web-pubsub-client/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/web-pubsub/web-pubsub-client/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，328 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：7 个
- 首次发布：2022-12-09T01:41:30.606Z
- 最新版本发布：2026-06-29T03:13:17.304Z
- 近 30 天下载量：407004（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：349（近 12 个月 49 个）

## 中文简介

Azure Web PubSub 客户端

## 安装

```sh
npm install @azure/web-pubsub-client
```

也可以使用：`pnpm add @azure/web-pubsub-client`、`yarn add @azure/web-pubsub-client`、`bun add @azure/web-pubsub-client`

## README

# JavaScript 的 Web PubSub 客户端库

[阿苏尔网络 PubSub](https://aka.ms/awps/doc) 是一种云服务,它帮助开发者在网络应用程序中轻松地建立实时功能,并具有规模化的发布订阅模式.

任何需要服务器和客户端之间或客户端之间按照发布订阅模式实时发送消息的情景都可以从使用Web PubSub中受益. 开发者不再需要通过每隔一段时间发送重复的HTTP请求来对服务器进行投票,这是浪费和难以衡量的.

如下图所示,您的客户端与您的 Web PubSub 资源建立 WebSocket 连接 。 此客户端库 :

-   简化客户端连接管理
-   简化客户端发送信件
-   客户端连接意外下降后自动重试
-   从连接滴滴中恢复后可靠发送信息的数量和顺序

![overflow](https://user-images.githubusercontent.com/668244/140014067-25a00959-04dc-47e8-ac25-6957bd0a71ce.png)

此处所用术语的详情如下: [关键概念](https://npmcn.com/package/%40azure/web-pubsub-client/#readme-key-concepts) 节.

_此库托管于 [国家预防机制](https://www.npmjs.com/package/@azure/web-pubsub-client)。 。 。 ._

* * *

## 开始

### 目前得到支持的环境

-   [节点.js的LTS版本](https://github.com/nodejs/release#release-schedule)

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/free/)
-   A 类 [Web PubSub 资源](https://learn.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance)

### 1\. 安装 `@azure/web-pubsub-client` 软件包

```bash
npm install @azure/web-pubsub-client
```

### 2\. 连接您的 Web PubSub 资源

客户端使用客户端访问 URL 连接并认证服务,该服务遵循以下模式: `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`。客户端可以有几种方式获得客户端访问URL. 这个快速开始,你可以复制并粘贴一个 从Azure Portal下面显示。 (用于制作,您的客户端通常可以获得应用程序服务器上生成的客户端访问URL. [详见下文](https://npmcn.com/package/%40azure/web-pubsub-client/#readme-use-negotiation-server-to-generate-client-access-url) (中文(简体) )

![get\_client\_url](https://learn.microsoft.com/azure/azure-web-pubsub/media/howto-websocket-connect/generate-client-url.png)

如上图所示,客户端有权向一个特定团体发送消息并加入该团体。 "_组1_" ..

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();
```

### 3\. 加入团体

注意客户端只能收到来自其加入的组的信息,您需要添加回调以指定接收消息时的逻辑.

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// Starts the client connection with your Web PubSub resource
await client.start();

// A client needs to join the group it wishes to receive messages from it
const groupName = "group1";
await client.joinGroup(groupName);
```

### 4\. 向一组发送信息

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";
await client.joinGroup(groupName);

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");
```

### 5\. 启动上游活动(审查)

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const result = await client.invokeEvent("processOrder", { orderId: 1 }, "json");
console.log(`Invocation result: ${JSON.stringify(result.data)}`);
```

`invokeEvent` 发送一个 `invoke` 请求服务,等待关联 `invokeResponse`,然后返回有效载荷。 您可以通过传递中止引用 `{ abortSignal }`。 。 。 . _服务引发的援引尚未得到支持._

### 6\. 向一组发送信息(审查)

可将一个大型或连续的有效载荷作为所订购的碎片流发送给一个组,并在接收方消耗每个入行的溪流整体.

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");

// Receiving side: subscribe once, then consume each inbound stream with for-await.
client.onGroupStream(
  async (stream) => {
    const parts: string[] = [];
    try {
      for await (const message of stream) {
        parts.push(message.data as string);
      }
      console.log(`Stream ${stream.streamId} completed: ${parts.join("")}`);
    } catch (err) {
      console.log(
        `Stream ${stream.streamId} failed: ${
          (
            err as {
              name?: string;
            }
          ).name
        }`,
      );
    }
  },
  { handleFromStart: true },
);

await client.start();
const groupName = "group1";
await client.joinGroup(groupName);

// Sending side: write a logical stream in ordered fragments, then end it.
const stream = await client.openGroupStream(groupName);
await stream.write("hello ", "text");
await stream.write("world", "text");
await stream.end();
```

`onGroupStream` 返回订阅 `close()` 为不注册 听者。 每个回电都收到一个 `GroupStream` 这对它的碎片是有效的. `openGroupStream` 返回 a `GroupStreamWriter` 用于 `write` 碎片, `end` 流成功,或 `abort` 它有一个错误.

* * *

## 实例

### 添加连接、 断开和停止事件的回调

1.  当客户端成功连接到您的 Web PubSub 资源时 `connected` 触发事件.

```ts
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
```

2.  当一个客户端断开并无法恢复连接时 `disconnected` 触发事件.

```ts
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
```

3.  这个 `stopped` 当客户端断开时将触发事件 _财务报告和审定财务报表_ 客户端停止尝试重新连接。 这通常发生在 `client.stop()` 称为,或 `autoReconnect` 已禁用,或已到达重联的指定限制。 如果您想要重新启动客户端, 您可以打电话 `client.start()` 在停止的事件.

```ts
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});
```

* * *

### 使用谈判服务器生成客户端访问 URL 程序

在制作中,客户端通常从应用程序服务器取取客户端访问URL. 服务器持有连接字符串到您的 Web PubSub 资源, 在服务器库的帮助下生成客户端访问 URL `@azure/web-pubsub`。 。 。 .

#### 1\. 应用程序服务器

下面的代码片段是应用程序服务器曝光一个 `/negotiate` 路径并返回客户端访问 URL.

```ts
import express from "express";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const hubName = "sample_chat";
const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get(
  "/negotiate",
  async (
    _req: unknown,
    res: {
      json: (body: { url: string }) => void;
    },
  ) => {
    const token = await serviceClient.getClientAccessToken({
      roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"],
    });
    res.json({
      url: token.url,
    });
  },
);

app.listen(port, () =>
  console.log(`Application server listening at http://localhost:${port}/negotiate`),
);
```

#### 2\. 客户方

下面的代码片段是客户端的例子.

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    const negotiate = await fetch("/negotiate");
    const { url } = (await negotiate.json()) as {
      url: string;
    };
    return url;
  },
});

await client.start();
```

_要了解样本的完整代码,请参见: [样本浏览器](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/web-pubsub/web-pubsub-client/samples-browser)。 。 。 ._

* * *

### 客户端会从应用程序服务器或加入的组中导入信件

一个客户端可以添加回调来消耗来自应用程序服务器或组的信息. 请注意: `group-message` 客户端可以 _仅限_ 接收它加入的组信件.

```ts
// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
  console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});
```

* * *

### 处理复职失败

当一个客户端被断开并无法恢复时, 将会在您的 Web PubSub 资源中清除所有组上下文 。 这意味着当客户端重新连接时,它需要重新加入组. 默认情况下,客户端有 `autoRejoinGroup` 选项已启用.

不过,你应该知道 `autoRejoinGroup`限制.

-   客户端只能重新加入最初由客户端代码加入的组 _没有_ 根据服务器侧码.
-   "rejoin group"操作可能由于各种原因而失败,例如客户端没有加入组的许可. 在这种情况下,您需要添加回调处理此故障 .

```ts
import { WebPubSubClient } from "@azure/web-pubsub-client";

// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", (e) => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
});
```

* * *

### 操作和重试

默认情况下, 例如 `client.joinGroup()`, (中文(简体) ), `client.leaveGroup()`, (中文(简体) ), `client.sendToGroup()`, (中文(简体) ), `client.sendEvent()` 有三个复试。 您可以通过 `messageRetryOptions`。如果所有重试都失败,则会出现错误。 你可以继续重试 通过通过同样的 `ackId` 作为之前的重试,以便Web PubSub服务可以去除操作.

```ts
import { WebPubSubClient, SendMessageError } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id: number | undefined;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, { ackId: id });
}
```

* * *

### 指定子议定书

您可以更改子协议, 供客户使用 。 默认情况下,客户端使用 `json.reliable.webpubsub.azure.v1`。您可以选择使用 `json.reliable.webpubsub.azure.v1` 或者说 `json.webpubsub.azure.v1`。 。 。 .

```ts
import { WebPubSubClient, WebPubSubJsonProtocol } from "@azure/web-pubsub-client";

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", {
  protocol: WebPubSubJsonProtocol(),
});
```

```ts
import { WebPubSubClient, WebPubSubJsonReliableProtocol } from "@azure/web-pubsub-client";

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", {
  protocol: WebPubSubJsonReliableProtocol(),
});
```

* * *

## 关键概念

### 连接

一个连接,也叫客户端或客户端连接,代表个人WebSocket连接到Web PubSub. 成功连接时,由Web PubSub为该连接指定了独特的连接ID. 每个 `WebPubSubClient` 建立自己的专属连接.

### 恢复

如果一个客户端使用可靠的协议断开,一个新的WebSocket试图使用丢失连接的连接ID来建立. 如果新的WebSocket连接成功连接,则连接被恢复. 在整个客户端断开时,服务会保留客户端上下文以及客户端订阅的所有消息,当客户端恢复时,服务会将这些消息发送给客户端. 如果服务返回 WebSocket 错误代码 `1008` 或回收尝试持续超过30秒,回收失败.

### 重新连接

重新连接发生在客户端连接下降而无法恢复时. 重新连接开始一个新的连接,而新的连接有新的连接ID. 与恢复不同,服务将重新连接的客户端视为新的客户端连接. 客户端连接需要重新加入组. 默认情况下,客户端库在重新连接后重新加入组.

### 枢纽

中枢是一组客户端连接的逻辑概念. 通常,您使用一个中枢用于一个目的,例如聊天中枢,或者通知中枢. 当客户端连接被创建时,它会连接到一个中枢,在其存在期间,它属于那个中枢. 不同的应用程序可以通过使用不同的中枢名称来共享一个Web PubSub.

### 组

一组是连接到中枢的子集. 您可以在组中添加客户端连接, 或者随时从组中去除客户端连接 。 例如,当客户端加入聊天室,或者当客户端离开聊天室时,这个聊天室可以被认为是一个组. 一个客户端可以加入多个组,一个组可以包含多个客户端.

### 用户

连接到 Web PubSub 可以属于一个用户. 一个用户可能拥有多个连接,例如当一个用户通过多个设备或多个浏览器标签连接时.

* * *

## 客户端寿命

每个Web PubSub客户端都能够安全地缓存并用作应用程序寿命的单通. 已注册的事件召回与客户共享相同的寿命. 这意味着您可以随时添加或删除回调,注册状态在重新连接或客户端被停止后不会改变.

* * *

## Java 脚本套装

要在浏览器中使用这个客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 [捆绑文件](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/Bundling.md)。 。 。 .

* * *

## 解决问题

### 启用日志

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 `AZURE_LOG_LEVEL` 环境变量改为 `info`。 。 。 .

```bash
export AZURE_LOG_LEVEL=verbose
```

也可以在运行时通过呼叫启用日志 `setLogLevel` 输入 `@azure/logger`数字 :

```ts
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```

关于如何启用日志的更详细指示,您可以查看 [@ azure/ logger 包文件](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger)。 。 。 .

-   ### 现场追踪
    
    使用 [活追踪工具](https://learn.microsoft.com/azure/azure-web-pubsub/howto-troubleshoot-resource-logs) 从Web PubSub出入口查看直播流量.
    

* * *

## 额外资源

-   了解更多客户端权限, 查看 [权限](https://learn.microsoft.com/azure/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol#permissions)
    
-   [服务器 SDK - JavaScript 文档](https://aka.ms/awps/sdk/js)
    
-   [产品文档](https://aka.ms/awps/doc)
    
-   [样本](https://github.com/Azure/azure-webpubsub/tree/main/samples/javascript/)
    

* * *

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) 学习如何构建和测试密码.

## 常见问题

### @azure/web-pubsub-client 是什么？

Azure Web PubSub 客户端

### 如何安装 @azure/web-pubsub-client？

在项目目录运行 npm install @azure/web-pubsub-client，或使用 pnpm add / yarn add / bun add。

### @azure/web-pubsub-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/web-pubsub-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/web-pubsub-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/web-pubsub-client 可以商用吗？

@azure/web-pubsub-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/web-pubsub-client 的下载量有多少？

根据 npm 官方下载统计，@azure/web-pubsub-client 在 2026/10/08 – 2026/11/06 这 30 天内被下载 407,004 次，日均约 13,567 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/web-pubsub-client 还在维护吗？

最新版本 1\.1\.0 发布于 2026/06/29（4 个月前）；至今共发布 349 个版本，其中过去 12 个月发布了 49 个；首次发布于 2022/12/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。