ws: Node.js WebSocket 库技术文档

1. 安装指南

安装步骤

要安装 ws 库，请在终端中运行以下命令：

npm install ws

可选性能优化

为了提高性能，你可以选择安装 bufferutil 模块：

npm install --save-optional bufferutil

bufferutil 是一个二进制插件，可以加速 WebSocket 帧数据负载的掩码和解掩码操作。预编译的二进制文件适用于大多数流行的平台，因此你不需要在机器上安装 C++ 编译器。

如果你不想使用 bufferutil，可以通过设置环境变量 WS_NO_BUFFER_UTIL 来禁用它。

旧版 Node.js 的性能优化

如果你使用的是旧版 Node.js（v18.14.0 之前），还可以安装 utf-8-validate 模块：

npm install --save-optional utf-8-validate

这个模块包含了一个 buffer.isUtf8() 的二进制 polyfill。

同样，你可以通过设置环境变量 WS_NO_UTF_8_VALIDATE 来禁用它。

2. 项目的使用说明

基本使用

ws 是一个简单易用、性能卓越的 WebSocket 客户端和服务器实现。它通过广泛的测试，确保了其稳定性和可靠性。

浏览器支持

需要注意的是，ws 模块不能在浏览器中使用。浏览器客户端必须使用原生的 WebSocket 对象。如果你希望在 Node.js 和浏览器中无缝使用相同的代码，可以使用 isomorphic-ws 等 npm 包。

3. 项目 API 使用文档

WebSocket 类

ws 提供了 WebSocket 类，用于创建 WebSocket 客户端。以下是一些常用的 API：

创建 WebSocket 客户端

import WebSocket from 'ws';

const ws = new WebSocket('ws://www.host.com/path');

ws.on('open', function open() {
  ws.send('Hello Server');
});

ws.on('message', function message(data) {
  console.log('received: %s', data);
});

发送文本数据

ws.send('Hello Server');

发送二进制数据

const array = new Float32Array(5);
for (let i = 0; i < array.length; ++i) {
  array[i] = i / 2;
}
ws.send(array);

WebSocketServer 类

ws 还提供了 WebSocketServer 类，用于创建 WebSocket 服务器。

创建简单的 WebSocket 服务器

import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('message', function message(data) {
    console.log('received: %s', data);
  });

  ws.send('Hello Client');
});

处理外部 HTTP/S 服务器

import { createServer } from 'https';
import { readFileSync } from 'fs';
import { WebSocketServer } from 'ws';

const server = createServer({
  cert: readFileSync('/path/to/cert.pem'),
  key: readFileSync('/path/to/key.pem')
});
const wss = new WebSocketServer({ server });

wss.on('connection', function connection(ws) {
  ws.on('message', function message(data) {
    console.log('received: %s', data);
  });

  ws.send('Hello Client');
});

server.listen(8080);

4. 项目安装方式

通过 npm 安装

npm install ws

可选性能优化模块

npm install --save-optional bufferutil
npm install --save-optional utf-8-validate

通过以上步骤，你可以轻松安装并使用 ws 库来创建 WebSocket 客户端和服务器。