net.Socket 类

新增于: v0.3.4

此类是 TCP 套接字或流式 IPC 端点(在 Windows 上使用命名管道，否则使用 Unix 域套接字)的抽象。

它也是 EventEmitter。

net.Socket 可以由用户创建并直接用于与服务器交互。

例如，通过 net.createConnection() 返回它，因此用户可以使用它与服务器对话。

它也可以由 Node.js 创建并在接收到连接时传给用户。

例如，它被传给在 net.Server 上触发的 'connection' 事件的监听器，因此用户可以使用它与客户端进行交互。

new net.Socket([options])

版本历史

版本变更

v15.14.0

添加了中止信号支持。

v0.3.4

新增于: v0.3.4

options 可用的选项有：

fd 如果指定，则使用给定的文件描述符封装现有的套接字，否则将创建新的套接字。

allowHalfOpen 如果设置为 false，则当可读端结束时，套接字将自动结束可写端。

有关详细信息，请参阅 net.createServer() 和 'end' 事件。 默认值: false。

readable 当传入 fd 时，则允许在套接字上读取，否则将被忽略。 默认值: false。

writable 当传入 fd 时，则允许在套接字上写入，否则将被忽略。 默认值: false。

signal 可用于销毁套接字的中止信号。

创建新的套接字对象。

新创建的套接字可以是 TCP 套接字或流式 IPC 端点，这取决于它 connect() 什么。

'close' 事件

新增于: v0.1.90

hadError 如果套接字有传输错误，则为 true。

一旦套接字完全关闭就触发。

参数 hadError 是布尔值，表示套接字是否由于传输错误而关闭。

'connect' 事件

新增于: v0.1.90

'data' 事件

新增于: v0.1.90

接收到数据时触发。

参数 data 将是 Buffer 或 String。

数据的编码由 socket.setEncoding() 设置。

如果 Socket 触发 'data' 事件时没有监听器，则数据将丢失。

'drain' 事件

新增于: v0.1.90

当写缓冲区变空时触发。

可用于限制上传。

另请参阅：socket.write() 的返回值。

'end' 事件

新增于: v0.1.90

当套接字的另一端表示传输结束时触发，从而结束套接字的可读端。

默认情况下(allowHalfOpen 是 false)套接字将发送传输结束数据包，并在写出其挂起的写入队列后销毁其文件描述符。

但是，如果 allowHalfOpen 设置为 true，套接字将不会自动将其可写端 end()，从而允许用户写入任意数量的数据。

用户必须显式调用 end() 来关闭连接(即发回一个 FIN 数据包)。

'error' 事件

新增于: v0.1.90

发生错误时触发。

'close' 事件将在此事件之后直接调用。

'lookup' 事件

版本历史

版本变更

v5.10.0

现在支持 host 参数。

v0.11.3

新增于: v0.11.3

在解析主机名之后但在连接之前触发。

不适用于 Unix 套接字。

'ready' 事件

新增于: v9.11.0

当套接字准备好使用时触发。

'connect' 后立即触发。

'timeout' 事件

新增于: v0.1.90

如果套接字因不活动而超时则触发。

这只是通知套接字已空闲。

用户必须手动关闭连接。

socket.address()

新增于: v0.1.90

返回操作系统报告的绑定 address、地址 family 名称和套接字的 port：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.bufferSize

新增于: v0.3.8弃用于: v14.6.0

此属性显示为写入而缓冲的字符数。

缓冲区可能包含编码后长度未知的字符串。

所以这个数字只是缓冲区中字节数的近似值。

net.Socket 具有 socket.write() 始终有效的特性。

这是为了帮助用户快速启动和运行。

计算机无法始终跟上写入套接字的数据量。

网络连接可能太慢了。

Node.js 将在内部对写入套接字的数据进行排队，并在可能的情况下通过网络将其发送出去。

这种内部缓冲的结果是内存可能会增长。

经历过大型或不断增长的 bufferSize 的用户应该尝试使用 socket.pause() 和 socket.resume() 来"节流"他们程序中的数据流。

socket.bytesRead

新增于: v0.5.3

接收的字节数。

socket.bytesWritten

新增于: v0.5.3

发送的字节数。

socket.connect()

在给定的套接字上发起连接。

可能的语法有：

此函数是异步的。

建立连接后，将触发 'connect' 事件。

如果连接出现问题，则将触发 'error' 事件并将错误传给 'error' 监听器，而不是触发 'connect' 事件。

最后一个参数 connectListener(如果提供)将作为 'connect' 事件的监听器添加一次。

此函数仅用于在触发 'close' 之后重新连接套接字，否则可能导致未定义的行为。

socket.connect(options[, connectListener])

版本历史

版本变更

v12.10.0

添加了 onread 选项。

v6.0.0

选项 hints 现在在所有情况下都默认为 0。 以前，如果没有 family 选项，它将默认为 dns.ADDRCONFIG | dns.V4MAPPED。

v5.11.0

现在支持 hints 选项。

v0.1.90

新增于: v0.1.90

在给定的套接字上发起连接。

一般不需要这个方法，套接字应该用 net.createConnection() 创建和打开。

仅在实现自定义套接字时使用它。

对于 TCP 连接，可用的 options 是：

port 必需的。

套接字应连接到的端口。

host 套接字应连接到的主机。 默认值: 'localhost'。

localAddress 套接字应该连接的本地地址。

localPort 套接字应连接的本地端口。

family : IP 堆栈的版本。

必须是 4、6 或 0。

值 0 表示允许 IPv4 和 IPv6 地址。 默认值: 0。

对于 IPC 连接，可用的 options 是：

path 必需的。

客户端应该连接到的路径。

请参阅标识 IPC 连接的路径。

如果提供，则忽略上面特定于 TCP 的选项。

对于这两种类型，可用的 options 包括：

onread 如果指定，传入的数据存储在单个 buffer 中，并在数据到达套接字时传给提供的 callback。

这将导致流功能不提供任何数据。

套接字将像往常一样触发 'error'、'end' 和 'close' 等事件。

pause() 和 resume() 等方法也将按预期运行。

buffer | | 用于存储传入数据的可重用内存块或返回此类数据的函数。

callback 为每个传入数据块调用此函数。

传给它的有两个参数：写入 buffer 的字节数和对 buffer 的引用。

从此函数返回 false 以隐式 pause() 套接字。

该函数将在全局上下文中执行。

以下是使用 onread 选项的客户端示例：

const net = require('net');

net.connect({

port: 80,

onread: {

// 每次从套接字读取时重用 4KiB 缓冲区。

buffer: Buffer.alloc(4 * 1024),

callback: function(nread, buf) {

// 接收到的数据在 `buf` 中可用，从 0 到 `nread`。

console.log(buf.toString('utf8', 0, nread));

}

}

});

socket.connect(path[, connectListener])path 客户端应该连接到的路径。

请参阅标识 IPC 连接的路径。

connectListener socket.connect() 方法的常用参数。

将被添加为 'connect' 事件的监听器一次。

在给定的套接字上发起 IPC 连接。

socket.connect(port[, host][, connectListener])

新增于: v0.1.90

port 客户端应该连接到的端口。

host 客户端应该连接到的主机。

connectListener socket.connect() 方法的常用参数。

将被添加为 'connect' 事件的监听器一次。

在给定的套接字上发起 TCP 连接。

socket.connecting

新增于: v6.1.0

如果 true，则 socket.connect(options[, connectListener]) 已被调用且尚未完成。

它将保持 true 直到套接字连接，然后将其设置为 false 并触发 'connect' 事件。

请注意，socket.connect(options[, connectListener]) 回调是 'connect' 事件的监听器。

socket.destroy([error])

新增于: v0.1.90

确保此套接字上不再发生 I/O 活动。

销毁流并关闭连接。

socket.destroyed 指示连接是否被破坏。

一旦连接被破坏，就不能再使用它传输数据。

socket.end([data[, encoding]][, callback])

新增于: v0.1.90

encoding 仅当数据为 string 时使用。 默认值: 'utf8'。

callback 套接字完成时的可选回调。

半关闭套接字。

即，它发送一个 FIN 数据包。

服务器可能仍会发送一些数据。

socket.localAddress

新增于: v0.9.6

远程客户端连接的本地 IP 地址的字符串表示形式。

例如，在监听 '0.0.0.0' 的服务器中，如果客户端连接到 '192.168.1.1'，则 socket.localAddress 的值将是 '192.168.1.1'。

socket.localPort

新增于: v0.9.6

本地端口的数字表示。

例如，80 或 21。

socket.pause()

暂停读取数据。

也就是说，不会触发 'data' 事件。

用于限制上传。

socket.pending

新增于: v11.2.0, v10.16.0

如果套接字尚未连接，则为 true，要么是因为 .connect() 尚未被调用，要么是因为它仍在连接过程中(参见 socket.connecting)。

socket.ref()

新增于: v0.9.1

与 unref() 相反，如果它是唯一剩下的套接字(默认行为)，则在以前的 unref 套接字上调用 ref() 不会让程序退出。

如果套接字是 ref 的，再次调用 ref 将无效。

socket.remoteAddress

新增于: v0.5.10

远程 IP 地址的字符串表示形式。

例如，'74.125.127.100' 或 '2001:4860:a005::68'。

如果套接字被破坏(例如，如果客户端断开连接)，则值可能是 undefined。

socket.remoteFamily

新增于: v0.11.14

远程 IP 系列的字符串表示形式。

'IPv4' 或 'IPv6'。

socket.remotePort

新增于: v0.5.10

远程端口的数字表示。

例如，80 或 21。

socket.resume()

socket.setEncoding([encoding])

新增于: v0.1.90

socket.setKeepAlive([enable][, initialDelay])

版本历史

版本变更

v13.12.0, v12.17.0

添加了 TCP_KEEPCNT 和 TCP_KEEPINTVL 套接字选项的新默认值。

v0.1.92

新增于: v0.1.92

enable 默认值: false

initialDelay 默认值: 0

启用/禁用保持活动功能，并可选择在空闲套接字上发送第一个保持活动探测之前设置初始延迟。

设置 initialDelay(以毫秒为单位)以设置接收到的最后一个数据包和第一个保持活动探测之间的延迟。

将 0 设置为 initialDelay 将使该值与默认(或先前)设置保持不变。

启用保持活动功能将设置以下套接字选项：

SO_KEEPALIVE=1

TCP_KEEPIDLE=initialDelay

TCP_KEEPCNT=10

TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])

新增于: v0.1.90

noDelay 默认值: true

启用/禁用 Nagle 算法的使用。

创建 TCP 连接时，它将启用 Nagle 算法。

Nagle 的算法在数据通过网络发送之前延迟数据。

它试图以延迟为代价来优化吞吐量。

为 noDelay 传入 true 或不传入参数将禁用套接字的 Nagle 算法。

为 noDelay 传入 false 将启用 Nagle 的算法。

socket.setTimeout(timeout[, callback])

新增于: v0.1.90

将套接字设置为在套接字上 timeout 毫秒不活动后超时。

默认情况下 net.Socket 没有超时。

当空闲超时被触发时，套接字将收到 'timeout' 事件，但连接不会被切断。

用户必须手动调用 socket.end() 或 socket.destroy() 才能结束连接。

socket.setTimeout(3000);

socket.on('timeout', () => {

console.log('socket timeout');

socket.end();

});

如果 timeout 为 0，则禁用现有空闲超时。

可选的 callback 参数将被添加为 'timeout' 事件的单次监听器。

socket.timeout

新增于: v10.7.0

由 socket.setTimeout() 设置的套接字超时(以毫秒为单位)。

如果未设置超时，则为 undefined。

socket.unref()

新增于: v0.9.1

如果这是事件系统中唯一的活动套接字，则在套接字上调用 unref() 将允许程序退出。

如果套接字已经被 unref，则再次调用 unref() 将无效。

socket.write(data[, encoding][, callback])

新增于: v0.1.90

在套接字上发送数据。

第二个参数指定字符串情况下的编码。

它默认为 UTF8 编码。

如果整个数据被成功刷新到内核缓冲区，则返回 true。

如果所有或部分数据在用户内存中排队，则返回 false。

当缓冲区再次空闲时，将触发 'drain'。

可选的 callback 参数将在数据最终写完时执行(可能不会立即执行)。

有关更多信息，请参阅 Writable 流 write() 方法。

socket.readyState

新增于: v0.5.0

此属性将连接状态表示为字符串。

如果流正在连接，则 socket.readyState 是 opening。

如果流可读可写，则为 open。

如果流可读不可写，则为 readOnly。

如果流不可读写，则为 writeOnly。