# @clusterws/cws 中文文档

规范地址：https://npmcn.com/package/%40clusterws/cws/

版本：3\.0\.0
npm 元数据更新时间：2022-04-04T23:41:27.894Z
中文译文更新时间：2026-11-10T04:43:45.993Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clusterws/cws
原文对照：https://npmcn.com/package/%40clusterws/cws/?lang=original
项目主页：https://github.com/ClusterWS/cWS#readme
源码仓库：https://github.com/ClusterWS/cWS

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

- 包体积（解压后）：10.1 MB，492 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2018-11-26T06:37:10.231Z
- 最新版本发布：2020-07-04T06:57:36.762Z
- 近 30 天下载量：2172（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 0 个）

## 中文简介

cWS - 为节点.js快速执行 C++ WebSocket

## 安装

```sh
npm install @clusterws/cws
```

也可以使用：`pnpm add @clusterws/cws`、`yarn add @clusterws/cws`、`bun add @clusterws/cws`

## README

# 组装WS/cWS

###### 为 Node.js 快速 WebSocket 执行

[![npm version](https://badge.fury.io/js/%40clusterws%2Fcws.svg)](https://badge.fury.io/js/%40clusterws%2Fcws) [![travis build](https://travis-ci.org/ClusterWS/cWS.svg?branch=master)](https://travis-ci.org/ClusterWS/cWS)

## 重要说明

-   此寄存器为 [uWebSockets v0.14 (英语)](https://github.com/uNetworking/uWebSockets/tree/v0.14) 因此,有两个许可证 [麻省理工学院](https://github.com/ClusterWS/uWS/blob/master/LICENSE) 财务报告和审定财务报表 [津巴布韦](https://github.com/ClusterWS/uWS/blob/master/src/LICENSE)
-   考虑使用最新的 [uWebSockets (中文(简体) )](https://github.com/uNetworking/uWebSockets.js) 版本改为
-   你可以支持我通过 [帕特伦](https://www.patreon.com/clusterws) 财务报告和审定财务报表 [付费页](https://www.paypal.me/goriunov)

## 支持的节点版本

| CWS 版本 | 节点 10 | 节点 11 | 节点 12 | 节点13 | 节点14 |
| --- | --- | --- | --- | --- | --- |
| 3.0.0 (单位:千美元) | 页:1 | 页:1 | 第12.16条 | 第13.9条 | 页:1 |
| 2.0.0 (韩语) | 页:1 | 页:1 | 第12.16条 | 第13.9条 | 页:1 |
| 1.6.0 (简体中文) | 页:1 | 页:1 | & < 12.16 | 第13.9条 | 页:1 |

## 文档

#### 有用链接

-   [实例](https://npmcn.com/package/%40clusterws/cws/examples)
-   [更改日志](https://npmcn.com/package/%40clusterws/cws/CHANGELOG.md)

#### 目录

-   [安装](https://npmcn.com/package/%40clusterws/cws/#readme-user-content-installation)
-   [网页客户端](https://npmcn.com/package/%40clusterws/cws/#readme-user-content-websocket-client)
-   [Websocket 服务器](https://npmcn.com/package/%40clusterws/cws/#readme-user-content-websocket-server)
-   [安全 WebSocket 软件](https://npmcn.com/package/%40clusterws/cws/#readme-user-content-secure-websocket)
-   [在浏览器中处理 App Level Ping (例)](https://npmcn.com/package/%40clusterws/cws/#readme-user-content-handle-app-level-ping-in-browser-example)

### 安装

```js
npm i @clusterws/cws
```

### 网页客户端

键入 : [d.ts 客户](https://github.com/ClusterWS/cWS/blob/master/dist/client.d.ts)

导入 cws WebSocket :

```js
const { WebSocket } = require('@clusterws/cws');
```

连接到 WebSocket 服务器 :

```js
const socket = new WebSocket(/* ws server endpoint **/);
```

活动 `open` 当服务器接受连接并准备执行其它动作时, 将触发:

```js
socket.on('open', () => { });
// or like browser interface
socket.onopen = () => { };
```

活动 `error` 如果连接出错, 将触发 :

```js
socket.on('error', (err) => { });
// or like browser interface
socket.onerror = (err) => { };
```

活动 `close` 当连接被关闭时被触发 :

```js
// code: number and reason: string are optional
socket.on('close', (code, reason) => { });
// or like browser interface
socket.onclose = (code, reason) => { };
```

活动 `message` 当客户端收到信件时触发 :

```js
// receives string or binary

socket.on('message', (message) => { });
// or like browser interface
socket.onmessage = (message) => { };
```

活动 `ping` 当另一方发送 ping 检查连接是否仍在活动时, 将触发 :

```js
socket.on('ping', () => { });
```

活动 `pong` 于 `ping` 已发送, 并收到回复:

```js
socket.on('pong', () => { })
```

要发送信件使用 `send` 函数 :

```js
// send accepts string or binary
// will automatically identify type
socket.send(msg);

// will overwrite/specify message type to string (does not transform data to specified type)
socket.send(msg, { binary: false });

// will overwrite/specify message type to binary (does not transform data to specified type)
socket.send(msg, { binary: true });

// will call callback after message sent or errored
socket.send(msg, null, (err) => { });
```

要关闭连接, 您可以使用 `close` 或者说 `terminate` 方法:

```js
// clean close code and reason are optional
socket.close(code, reason);
// destroy socket 
socket.terminate()
```

使用 `ping` 函数可手动发送 ping :

```js
socket.ping();
// now just wait for `pong` event
```

要得到当前套接字准备状态可以使用 `readyState` 获取器 :

```js
socket.readyState; // -> OPEN (1) or CLOSED (3)

// check if socket open can be done by
if(socket.readyState === socket.OPEN) {}

// check if socket closed can be done by
if(socket.readyState === socket.CLOSED) {}
```

获取地址使用 `_socket` 获取器 :

```js
socket._socket;

// Returns some thing like (all fields could be undefined):
// {
//  remotePort,
//  remoteAddress,
//  remoteFamily
// }
```

**更多信息检查打字(`*.d.ts`文件在 [数字](https://github.com/ClusterWS/cWS/blob/master/dist) 文件夹**

### Websocket 服务器

键入 : [离/服务器.d.ts](https://github.com/ClusterWS/cWS/blob/master/dist/server.d.ts)

导入 cws WebSocket :

```js
const { WebSocket } = require('@clusterws/cws');
```

创建 WebSocket 服务器 :

```js
const wsServer = new WebSocket.Server({ 
  /**
   * port?: number (creates server and listens on provided port)
   * host?: string (provide host if necessary with port)
   * path?: string (url at which accept ws connections)
   * server?: server (provide already existing server)
   * noDelay?: boolean (set socket no delay)
   * noServer?: boolean (use this when upgrade done outside of cws)
   * maxPayload?: number 
   * perMessageDeflate?: boolean | { serverNoContextTakeover: boolean;}
   * verifyClient?: (info: ConnectionInfo, next: VerifyClientNext) => void (use to allow or decline connections)
   **/ 
 }, () => {
  // callback called when server is ready
  // is not called when `noServer: true` or `server` is provided
  // from outside
});
```

活动 `connection` 当新客户端连接到服务器时触发 :

```js
// `ws` is websocket client all available options 
// can be found in `Websocket Client` section above
// `req` is http upgrade request
wsServer.on('connection', (ws, req) => {})
```

活动 `error` 当服务器出现一些问题时触发 `noServer` 实值 `false:`

```js
// on error event will NOT include httpServer errors IF
// server was passed under server parameter { server: httpServer },
// you can register on 'error' listener directly on passed server
wsServer.on('error', (err) => { })
```

活动 `close` 在您拨打后触发 `wsServer.close()` 函数,如果 `cb` 两者均提供 `cb` 继续 `close` 将触发听众 :

```js
wsServer.on('close', () => { })
```

让所有连接的客户端使用 `clients` 获取器 :

```js
wsServer.clients;

// loop thought all clients:
wsServer.clients.forEach((ws) => { });

// get number of clients:
wsServer.clients.length;
```

向所有使用的连接客户端发送信件 `broadcast` 方法 :

```js
// broadcast string
wsServer.broadcast(message);

// broadcast binary
wsServer.broadcast(message, { binary: true });
```

cWS 支持自动拨打 `startAutoPing` 函数 :

```js
wsServer.startAutoPing(interval, appLevel);

// send ping to each client every 10s and destroy client if no pong received 
wsServer.startAutoPing(10000);

// pass true as second parameter to run app level ping
// this is mainly used for browser to track pings at client level
// as they do not expose on ping listener 
// look for browser client side implementation at the bottom
// `Handle App Level Ping In Browser (example)`
wsServer.startAutoPing(10000, true);
```

停止服务器使用 `close` 函数 :

```js
wsServer.close(() => {
  // triggered after server has been stopped
})
```

`handleUpgrade` 和 `noServer` (与 `ws` 模块)

```js
const wss = new WebSocket.Server({ noServer: true });
const server = http.createServer();

wss.on('connection', (ws, req) => { })

server.on('upgrade', (request, socket, head) => {
  wss.handleUpgrade(request, socket, head, (ws) => {
      wss.emit('connection', ws, request);
  });
});
```

**更多信息检查打字(`*.d.ts`文件在 [数字](https://github.com/ClusterWS/cWS/blob/master/dist) 文件夹**

### 安全 WebSocket 软件

你用得着 `wss://` 与 `cws` 通过提供 `https` 服务器到 `cws` 设置 `secureProtocol` https 选项:

```js
const { readFileSync } = require('fs');
const { createServer }  = require('https');
const { WebSocket, secureProtocol  } = require('@clusterws/cws');

const options = {
  key: readFileSync(/** path to key */),
  cert: readFileSync(/** path to certificate */),
  secureProtocol
  // ...other Node HTTPS options
};

const server = createServer(options);
const wsServer = new WebSocket.Server({ server });
// your secure ws is ready (do your usual things)

server.listen(port, () => {
  console.log('Server is running');
})
```

**更详细的例子检查 [实例](https://github.com/ClusterWS/cWS/blob/master/examples) 文件夹**

### 在浏览器中处理 App Level Ping (例)

处理自定义 App 级别 `ping`, (中文(简体) ), `pong` 客户端没有 `onping` 财务报告和审定财务报表 `onpong` 浏览器等可用的收听器 .

**说明** 如果你所有的客户都有 `onping` 财务报告和审定财务报表 `onpong` 听众不发送 `appLevelPing` 从服务器接来 如果您启用了 ApplevelPing, 您需要为连接到服务器的每个客户端库执行类似的处理器 .

```js
const PING = 57;
const PONG = new Uint8Array(['A'.charCodeAt()]);

socket.binaryType = 'arraybuffer';

socket.onmessage = function (message) {
    // note actually sent message in
    // browser default WebSocket is under `message.data`

    // check if message is not string 
    if (typeof message.data !== 'string') {
        // transform it to Uint8Array
        let buffer = new Uint8Array(message.data);

        // Check if it is actually ping from the server
        if (buffer.length === 1 && buffer[0] === PING) {
            // this is definitely `ping` event you can call custom on ping handler 
            // also must send back immediately pong to the server 
            // otherwise server will disconnect this client
            return socket.send(PONG);
        }
    }

    // process with your logic
}
```

## 常见问题

### @clusterws/cws 是什么？

cWS - 为节点\.js快速执行 C\+\+ WebSocket

### 如何安装 @clusterws/cws？

在项目目录运行 npm install @clusterws/cws，或使用 pnpm add / yarn add / bun add。

### @clusterws/cws 支持 TypeScript 吗？

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

### @clusterws/cws 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @clusterws/cws 可以商用吗？

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

### @clusterws/cws 的下载量有多少？

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

### @clusterws/cws 还在维护吗？

最新版本 3\.0\.0 发布于 2020/07/04（6 年前）；至今共发布 33 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/11/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。