Node.js v18.18.2 文档

IPC支持#

node:net模块在 Windows 上支持带有命名管道的 IPC，在其他操作系统上支持 Unix 域套接字。

识别 IPC 连接的路径#

net.connect()、 net.createConnection()、 server.listen()和 socket.connect()采用path参数来标识 IPC 端点。

在 Unix 上，本地域也称为 Unix 域。该路径是文件系统路径名。它被截断为取决于操作系统的长度 sizeof(sockaddr_un.sun_path) - 1。Linux 上的典型值为 107 字节，macOS 上的典型值为 103 字节。如果 Node.js API 抽象创建了 Unix 域套接字，它也会取消 Unix 域套接字的链接。例如， net.createServer()可能会创建一个 Unix 域套接字，而 server.close()将取消它的链接。但是，如果用户在这些抽象之外创建 Unix 域套接字，则用户将需要删除它。当 Node.js API 创建 Unix 域套接字但程序崩溃时，情况也是如此。简而言之，Unix 域套接字将在文件系统中可见，并将持续存在，直到取消链接。

在 Windows 上，本地域是使用命名管道实现的。该路径必须引用\\?\pipe\或\\.\pipe\ 中的条目。允许使用任何字符，但后者可能会对管道名称进行一些处理，例如解析.. 序列。不管它看起来如何，管道命名空间是扁平的。管道 不会持续存在。当对它们的最后一个引用关闭时，它们将被删除。与 Unix 域套接字不同，Windows 将在所属进程退出时关闭并删除管道。

JavaScript 字符串转义需要使用额外的反斜杠转义来指定路径，例如：

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl')); copy

类：net.BlockList#

BlockList对象可与某些网络 API 一起使用，以指定禁止对特定 IP 地址、IP 范围或 IP 子网的入站或出站访问的规则。

blockList.addAddress(address[, type])#

• address <字符串> | <net.SocketAddress> IPv4 或 IPv6 地址。
• type <string> 'ipv4'或'ipv6'。默认值： 'ipv4'。

添加一条规则来阻止给定的 IP 地址。

blockList.addRange(start, end[, type])#

• start <字符串> | <net.SocketAddress>范围中的起始 IPv4 或 IPv6 地址。
• end <字符串> | <net.SocketAddress>范围内的结束 IPv4 或 IPv6 地址。
• type <string> 'ipv4'或'ipv6'。默认值： 'ipv4'。

添加一条规则以阻止从start（含）到 end（含）的 IP 地址范围。

blockList.addSubnet(net, prefix[, type])#

• net <字符串> | <net.SocketAddress>网络 IPv4 或 IPv6 地址。
• prefix <number> CIDR 前缀位数。对于 IPv4，该值必须是介于0和32之间的值。对于 IPv6，该值必须介于 0和128之间。
• type <string> 'ipv4'或'ipv6'。默认值： 'ipv4'。

添加规则以阻止指定为子网掩码的 IP 地址范围。

blockList.check(address[, type])#

• address <字符串> | <net.SocketAddress>要检查的 IP 地址
• type <string> 'ipv4'或'ipv6'。默认值： 'ipv4'。
• 返回：<布尔值>

如果给定的 IP 地址与添加到 BlockList的任何规则匹配， 则返回true。

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // Prints: true
console.log(blockList.check('10.0.0.3'));  // Prints: true
console.log(blockList.check('222.111.111.222'));  // Prints: false

// IPv6 notation for IPv4 addresses works:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true copy

blockList.rules#

• 类型：<字符串[]>

添加到阻止列表的规则列表。

类：net.SocketAddress#

new net.SocketAddress([options])#

• options <对象>
  • address <string> IPv4 或 IPv6 字符串形式的网络地址。 默认值：'127.0.0.1'（如果family为'ipv4'；'::'如果family是 'ipv6'。
  • family <string> 'ipv4'或'ipv6'之一。 默认值：'ipv4'。
  • flowlabel <number>仅当family为'ipv6'时使用 IPv6 流标签。
  • port <number> IP 端口。

socketaddress.address#

• 输入<字符串>

socketaddress.family#

• 输入<string> 'ipv4'或'ipv6'。

socketaddress.flowlabel#

• 输入<数字>

socketaddress.port#

• 输入<数字>

类：net.Server#

• 扩展：<EventEmitter>

此类用于创建 TCP 或IPC服务器。

new net.Server([options][, connectionListener])#

• options <对象>请参阅 net.createServer([options][, connectionListener])。
• connectionListener <Function>自动设置为 'connection'事件的监听器。
• 返回：<net.Server>

net.Server是具有以下事件的EventEmitter ：

事件：'close'#

服务器关闭时发出。如果连接存在，则在所有连接结束之前不会发出此事件。

事件：'connection'#

• <net.Socket>连接对象

建立新连接时发出。socket是net.Socket的实例 。

事件：'error'#

• <错误>

发生错误时发出。与net.Socket不同，除非手动调用server.close() ，否则不会在此事件之后直接发出 'close' 事件。请参阅server.listen()讨论中的示例 。

事件：'listening'#

调用server.listen()后绑定服务器时发出。

事件：'drop'#

当连接数达到阈值server.maxConnections时，服务器将丢弃新连接并发出'drop'事件。如果是 TCP 服务器，则参数如下，否则参数为undefined。

• data <Object>传递给事件侦听器的参数。
  • localAddress <string> 本地地址。
  • localPort <number>本地端口。
  • localFamily <string>当地家庭。
  • remoteAddress <string>远程地址。
  • remotePort <number>远程端口。
  • remoteFamily <string>远程 IP 系列。'IPv4'或'IPv6'。

server.address()#

• 返回：<对象> | <字符串> | <空>

如果侦听 IP 套接字，则返回操作系统报告的绑定address、地址family名称和服务器的port （有助于查找哪个获取操作系统分配的地址时分配了端口）： { port: 12346, family: 'IPv4', address: '127.0.0.1' }。

对于侦听管道或 Unix 域套接字的服务器，名称以字符串形式返回。

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
}); copy

server.address()在'listening'事件发出之前或调用server.close()之后返回 null 。

server.close([callback])#

• callback <Function>服务器关闭时调用。
• 返回：<net.Server>

停止服务器接受新连接并保留现有连接。该函数是异步的，当所有连接结束并且服务器发出'close'事件时，服务器最终关闭。一旦 'close' 事件发生，就会调用可选的callback。与该事件不同的是，如果服务器关闭时未打开，则将使用Error作为唯一参数来调用该事件。

server[Symbol.asyncDispose]()#

调用server.close()并返回一个在服务器关闭时履行的 Promise 。

server.getConnections(callback)#

• callback <函数>
• 返回：<net.Server>

异步获取服务器上的并发连接数。当套接字发送到叉子时起作用。

回调应采用两个参数err和count。

server.listen()#

启动服务器侦听连接。net.Server可以是 TCP 或IPC服务器，具体取决于它侦听的内容。

可能的签名：

• server.listen(handle[, backlog][, callback])
• server.listen(options[, callback])
• IPC服务器 的server.listen(path[, backlog][, callback])
• TCP 服务器的server.listen([port[, host[, backlog]]][, callback])

该函数是异步的。当服务器开始侦听时， 将发出'listening'事件。最后一个参数callback 将被添加为'listening'事件的侦听器。

所有listen()方法都可以采用backlog参数来指定待处理连接队列的最大长度。实际长度将由操作系统通过 sysctl 设置确定，例如Linux 上的tcp_max_syn_backlog和somaxconn 。此参数的默认值为 511（而不是 512）。

所有net.Socket均设置为SO_REUSEADDR（有关详细信息，请参阅socket(7)）。

当且仅当第一次server.listen() 调用期间出现错误或已调用server.close() 时，才能再次调用 server.listen()方法。否则，将会抛出ERR_SERVER_ALREADY_LISTEN错误。

监听时最常见的错误之一是EADDRINUSE。当另一台服务器已经在侦听请求的 port / path / handle时，就会发生这种情况。处理此问题的一种方法是在一段时间后重试：

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
}); copy

server.listen(handle[, backlog][, callback])#

• handle <对象>
• backlog <number> server.listen()函数的公共参数
• callback <函数>
• 返回：<net.Server>

启动服务器侦听已绑定到端口、Unix 域套接字或 Windows 命名管道的给定handle上的连接。

handle对象可以是服务器、套接字（任何具有底层_handle成员的对象）或具有fd成员且为有效文件的对象描述符。

Windows 不支持侦听文件描述符。

server.listen(options[, callback])#

• options <对象>必需。支持以下属性：
  • port <数字>
  • host <字符串>
  • path <string>如果指定了port将被忽略。请参阅 识别 IPC 连接的路径。
  • backlog <number> server.listen()函数的公共参数 。
  • exclusive <布尔值> 默认值： false
  • readableAll <boolean>对于 IPC 服务器，使管道对所有用户都可读。默认值： false。
  • writableAll <boolean>对于 IPC 服务器，使管道可供所有用户写入。默认值： false。
  • ipv6Only <boolean>对于 TCP 服务器，将ipv6Only设置为true将禁用双栈支持，即绑定到主机::获胜不要让 0.0.0.0受到束缚。默认值： false。
  • signal <AbortSignal>可用于关闭侦听服务器的 AbortSignal。
• callback <函数> 函数。
• 返回：<net.Server>

如果指定了port ，则其行为与server.listen([port[, host[, backlog]]][, callback])相同 。否则，如果指定了path ，则其行为与server.listen(path[, backlog][, callback])相同 。如果没有指定它们，将会抛出错误。

如果exclusive为false（默认），则集群工作线程将使用相同的底层句柄，从而允许共享连接处理职责。当 exclusive为true时，句柄不共享，并且尝试端口共享会导致错误。下面显示了侦听独占端口的示例。

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true,
}); copy

当exclusive为true并且共享底层句柄时，多个工作线程可能会查询具有不同待办事项的句柄。在这种情况下，将使用传递给主进程的第一个backlog 。

以 root 身份启动 IPC 服务器可能会导致非特权用户无法访问服务器路径。使用readableAll和writableAll将使所有用户都可以访问服务器。

如果启用了signal选项，则在相应的 AbortController 上调用 .abort()与在服务器上调用.close()类似：

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort(); copy

server.listen(path[, backlog][, callback])#

• path <string>服务器应侦听的路径。请参阅 识别 IPC 连接的路径。
• backlog <number> server.listen()函数的公共参数。
• callback <函数> .
• 返回：<net.Server>

启动IPC服务器侦听给定path上的连接。

server.listen([port[, host[, backlog]]][, callback])#

• port <数字>
• host <字符串>
• backlog <number> server.listen()函数的公共参数。
• callback <函数> .
• 返回：<net.Server>

启动 TCP 服务器侦听给定port和host上的连接。

如果省略port或为 0，则操作系统将分配任意未使用的端口，可以在发出 'listening'事件 后使用server.address().port检索该端口。

如果省略 host ，则当 IPv6 可用时， 服务器将接受未指定的 IPv6 地址( :: ) 上的连接，否则接受未指定的 IPv4 地址( 0.0.0.0 )上的连接。

在大多数操作系统中，侦听未指定的 IPv6 地址( :: ) 可能会导致net.Server也侦听未指定的 IPv4 地址 ( 0.0.0.0 )。

server.listening#

• <boolean>指示服务器是否正在侦听连接。

server.maxConnections#

• <整数>

设置此属性可在服务器的连接计数变高时拒绝连接。

一旦将套接字发送给具有child_process.fork()的子级，则不建议使用此选项。

server.ref()#

• 返回：<net.Server>

与unref()相反，在之前的 unref ed 服务器上调用 ref()不会让 程序退出，如果它是唯一剩下的服务器（默认行为）。如果服务器已ref ed，则再次调用ref()将无效。

server.unref()#

• 返回：<net.Server>

如果服务器是事件系统中唯一的事件服务器，则在服务器上调用unref()将允许程序退出。如果服务器已经unref ed，则再次调用 unref()将无效。

类：net.Socket#

• 扩展：<stream.Duplex>

此类是 TCP 套接字或流式IPC端点的抽象（在 Windows 上使用命名管道，否则使用 Unix 域套接字）。它也是一个EventEmitter。

用户可以创建net.Socket并直接用于与服务器交互。例如，它由net.createConnection()返回，因此用户可以使用它与服务器通信。

它也可以由 Node.js 创建并在收到连接时传递给用户。例如，它被传递到 在net.Server 上发出的 'connection' 事件的侦听器，以便用户可以使用它与客户端交互。

new net.Socket([options])#

• options <对象>可用选项有：
  • fd <number>如果指定，则使用给定的文件描述符环绕现有套接字，否则将创建一个新套接字。
  • allowHalfOpen <boolean>如果设置为false，那么当可读端结束时，套接字将自动结束可写端。有关详细信息，请参阅 net.createServer()和'end'事件。默认值： false。
  • readable <boolean>当传递fd时允许在套接字上读取，否则忽略。默认值： false。
  • writable <boolean>当传递fd时允许在套接字上写入，否则忽略。默认值： false。
  • signal <AbortSignal>可用于销毁套接字的中止信号。
• 返回：<net.Socket>

创建一个新的套接字对象。

新创建的套接字可以是 TCP 套接字，也可以是流式IPC 端点，具体取决于它的用途。connect()。

事件：'close'#

• hadError <boolean> true如果套接字出现传输错误。

套接字完全关闭后发出。参数hadError是一个布尔值，表示套接字是否由于传输错误而关闭。

事件：'connect'#

成功建立套接字连接时发出。请参阅net.createConnection()。

事件：'data'#

• <缓冲区> | <字符串>

收到数据时发出。参数data将为Buffer或 String。数据的编码由socket.setEncoding()设置。

当Socket 发出'data'事件时，如果没有侦听器，数据将会丢失。

事件：'drain'#

当写入缓冲区变空时发出。可用于限制上传。

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

事件：'end'#

当套接字的另一端发出传输结束信号时发出，从而结束套接字的可读端。

默认情况下（allowHalfOpen是false）套接字将发送回传输结束数据包，并在写出其挂起的写入队列后销毁其文件描述符。但是，如果allowHalfOpen设置为true，套接字将不会自动end()其可写端，从而允许用户写入任意数量的数据。用户必须显式调用 end()来关闭连接（即发回 FIN 数据包）。

事件：'error'#

• <错误>

发生错误时发出。在此事件之后将直接调用'close'事件。

事件：'lookup'#

在解析主机名之后但在连接之前发出。不适用于 Unix 套接字。

• err <错误> | <null>错误对象。请参阅dns.lookup()。
• address <string> IP 地址。
• family <数字> | <null>地址类型。请参阅dns.lookup()。
• host <string>主机名。

事件：'ready'#

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

在'connect'之后立即触发。

事件：'timeout'#

如果套接字因不事件而超时则发出。这只是为了通知套接字已空闲。用户必须手动关闭连接。

另请参阅：socket.setTimeout()。

socket.address()#

• 返回：<对象>

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

socket.autoSelectFamilyAttemptedAddresses#

• <字符串[]>

仅当在socket.connect(options)中启用系列自动选择算法 并且它是已尝试的地址的数组时，此属性才存在。

每个地址都是一个$IP:$PORT形式的字符串。如果连接成功，则最后一个地址就是套接字当前连接的地址。

socket.bufferSize#

• <整数>

此属性显示缓冲写入的字符数。缓冲区可能包含编码后长度未知的字符串。所以这个数字只是缓冲区中字节数的近似值。

net.Socket具有socket.write()始终有效的属性。这是为了帮助用户快速启动并运行。计算机无法始终跟上写入套接字的数据量。网络连接可能太慢。Node.js 会在内部对写入套接字的数据进行排队，并在可能的情况下通过线路将其发送出去。

这种内部缓冲的结果是内存可能会增长。遇到较大或不断增长的bufferSize的用户应尝试使用 socket.pause()和socket.resume() “限制”程序中的数据流。

socket.bytesRead#

• <整数>

接收到的字节数。

socket.bytesWritten#

• <整数>

发送的字节数。

socket.connect()#

在给定套接字上启动连接。

可能的签名：

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) 用于IPC连接。
• socket.connect(port[, host][, connectListener]) 用于 TCP 连接。
• 返回：<net.Socket>套接字本身。

该函数是异步的。建立连接后， 将发出'connect'事件。如果连接出现问题，将发出'error'事件，而不是'connect'事件，并将错误传递到'error'侦听器。最后一个参数connectListener（如果提供）将被添加为'connect'事件的侦听器Once。

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

socket.connect(options[, connectListener])#

• options <对象>
• connectListener <Function> socket.connect()方法的公共参数 。将被添加为'connect'事件的侦听器一次。
• 返回：<net.Socket>套接字本身。

在给定套接字上启动连接。通常不需要此方法，应使用net.createConnection()创建并打开套接字。仅在实现自定义 Socket 时使用此选项。

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

• port <number>必填。套接字应连接到的端口。
• host <string>套接字应连接到的主机。默认值： 'localhost'。
• localAddress <string>套接字应连接的本地地址。
• localPort <number>套接字应连接的本地端口。
• family <number>：IP 堆栈的版本。必须是4、6或0。值 0表示允许 IPv4 和 IPv6 地址。默认值： 0。
• hints <number>可选的dns.lookup()提示。
• lookup <Function>自定义查找函数。默认值： dns.lookup()。
• noDelay <boolean>如果设置为true，则在建立套接字后立即禁用 Nagle 算法。默认值： false。
• keepAlive <boolean>如果设置为true，则在建立连接后立即启用套接字上的保持事件功能，类似于 socket.setKeepAlive([enable][, initialDelay])中所做的操作。 默认值： false。
• keepAliveInitialDelay <number>如果设置为正数，则设置在空闲套接字上发送第一个保活探测之​​前的初始延迟。默认值： 0。
• autoSelectFamily <boolean>：如果设置为true ，它将启用松散实现RFC 8305第 5 节的系列自动检测算法。传递给查找的all选项设置为true，并且套接字尝试按顺序连接到所有获得的 IPv6 和 IPv4 地址，直到建立连接。首先尝试第一个返回的 AAAA 地址，然后尝试第一个返回的 A 地址，然后尝试第二个返回的 AAAA 地址，依此类推。每次连接尝试都会经过autoSelectFamilyAttemptTimeout选项指定的时间， 然后超时并尝试下一个地址。如果family选项不是0或设置了localAddress，则忽略。如果至少一个连接成功，则不会发出连接错误。 默认值：最初为false，但可以在运行时使用net.setDefaultAutoSelectFamily(value) 或通过命令行选项--enable-network-family-autoselection进行更改。
• autoSelectFamilyAttemptTimeout <number> ：使用autoSelectFamily选项时，在尝试下一个地址之前等待连接尝试完成的时间（以毫秒为单位）。如果设置为小于10的正整数，则将使用 值10 。默认值：最初为250，但可以在运行时使用net.setDefaultAutoSelectFamilyAttemptTimeout(value)进行更改

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

• path <string>必需。客户端应连接到的路径。请参阅识别 IPC 连接的路径。如果提供，则忽略上面的 TCP 特定选项。

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

• onread <Object>如果指定，传入数据将存储在单个buffer中，并在数据到达套接字时 传递到提供的callback 。这将导致流功能不提供任何数据。套接字将 像平常一样发出'error'、'end'和'close'等事件。像pause()和resume()这样的方法也将按预期运行。
  • buffer <缓冲区> | <Uint8Array> | <Function>用于存储传入数据的可重用内存块或返回此类数据的函数。
  • callback <Function>对于每个传入数据块都会调用此函数。向其传递两个参数：写入buffer的字节数 和对buffer的引用。从此函数返回false以隐式pause()套接字。该函数将在全局上下文中执行。

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

const net = require('node:net');
net.connect({
  port: 80,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
}); copy

socket.connect(path[, connectListener])#

• path <string>客户端应连接到的路径。请参阅 识别 IPC 连接的路径。
• connectListener <Function> socket.connect()方法的公共参数 。将被添加为'connect'事件的侦听器一次。
• 返回：<net.Socket>套接字本身。

在给定套接字上启动IPC连接。

socket.connect(options[, connectListener])的别名 以{ path: path }调用为options。

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

• port <number>客户端应连接的端口。
• host <string>客户端应连接到的主机。
• connectListener <Function> socket.connect()方法的公共参数 。将被添加为'connect'事件的侦听器一次。
• 返回：<net.Socket>套接字本身。

在给定套接字上启动 TCP 连接。

socket.connect(options[, connectListener])的别名 以{port: port, host: host}调用为options。

socket.connecting#

• <布尔值>

如果true， 则调用socket.connect(options[, connectListener])且尚未完成。它将保持true直到套接字连接，然后将其设置为false并发出'connect'事件。请注意， socket.connect(options[, connectListener])回调是'connect'事件 的侦听器。

socket.destroy([error])#

• error <对象>
• 返回：<net.Socket>

确保此套接字上不再发生 I/O 事件。销毁流并关闭连接。

请参阅writable.destroy()了解更多详情。

socket.destroyed#

• <boolean>指示连接是否被破坏。一旦连接被破坏，就无法使用它传输更多数据。

请参阅writable.destroyed了解更多详情。

socket.destroySoon()#

写入所有数据后销毁套接字。如果已发出'finish'事件，则套接字将立即销毁。如果套接字仍然可写，它会隐式调用socket.end()。

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

• data <字符串> | <缓冲区> | <Uint8Array>
• encoding <string>仅当数据为string时使用。默认值： 'utf8'。
• callback <Function>套接字完成时的可选回调。
• 返回：<net.Socket>套接字本身。

半关闭套接字。即发送FIN数据包。服务器可能仍会发送一些数据。

请参阅writable.end()了解更多详情。

socket.localAddress#

• <字符串>

远程客户端连接的本地 IP 地址的字符串表示形式。例如，在侦听'0.0.0.0' 的服务器中，如果客户端连接到'192.168.1.1' ，则socket.localAddress的值将为 '192.168.1.1'。

socket.localPort#

• <整数>

本地端口的数字表示。例如，80或21。

socket.localFamily#

• <字符串>

本地 IP 系列的字符串表示形式。'IPv4'或'IPv6'。

socket.pause()#

• 返回：<net.Socket>套接字本身。

暂停数据读取。也就是说，不会发出'data'事件。对于限制上传很有用。

socket.pending#

• <布尔值>

如果套接字尚未连接，则为true ，因为.connect() 尚未被调用，或者因为它仍在连接过程中（请参阅socket.connecting）。

socket.ref()#

• 返回：<net.Socket>套接字本身。

与unref()相反，在之前unref ed 的套接字 上调用ref()不会让程序退出，如果它是唯一剩下的套接字（默认行为）。如果套接字已ref ed，则再次调用ref将无效。

socket.remoteAddress#

• <字符串>

远程 IP 地址的字符串表示形式。例如， '74.125.127.100'或'2001:4860:a005::68'。如果套接字被破坏（例如，如果客户端断开连接），则值可能为undefined 。

socket.remoteFamily#

• <字符串>

远程 IP 系列的字符串表示形式。'IPv4'或'IPv6'。如果套接字被破坏（例如，如果客户端断开连接），则值可能为undefined 。

socket.remotePort#

• <整数>

远程端口的数字表示。例如，80或21。如果套接字被破坏（例如，如果客户端断开连接），则值可能为undefined 。

socket.resetAndDestroy()#

• 返回：<net.Socket>

通过发送 RST 数据包关闭 TCP 连接并销毁流。如果该 TCP 套接字处于连接状态，一旦连接就会发送 RST 数据包并销毁该 TCP 套接字。否则，它将调用socket.destroy并出现ERR_SOCKET_CLOSED错误。如果这不是 TCP 套接字（例如管道），则调用此方法将立即抛出ERR_INVALID_HANDLE_TYPE错误。

socket.resume()#

• 返回：<net.Socket>套接字本身。

调用socket.pause()后继续读取。

socket.setEncoding([encoding])#

• encoding <字符串>
• 返回：<net.Socket>套接字本身。

将套接字的编码设置为Readable Stream。请参阅 readable.setEncoding()了解更多信息。

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

• enable <布尔值> 默认值： false
• initialDelay <数字> 默认值： 0
• 返回：<net.Socket>套接字本身。

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

设置initialDelay（以毫秒为单位）以设置收到的最后一个数据包与第一个 keepalive 探测之间的延迟。将initialDelay设置为 0将使默认（或之前）设置的值保持不变。

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

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay
• TCP_KEEPCNT=10
• TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])#

• noDelay <布尔值> 默认值： true
• 返回：<net.Socket>套接字本身。

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

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

Nagle 的算法会在数据通过网络发送之前延迟数据。它试图以延迟为代价来优化吞吐量。

为noDelay传递true或不传递参数将禁用 Nagle 的套接字算法。将false传递给noDelay将启用 Nagle 算法。

socket.setTimeout(timeout[, callback])#

• timeout <数字>
• callback <函数>
• 返回：<net.Socket>套接字本身。

将套接字设置为在套接字不事件timeout毫秒后超时。默认情况下，net.Socket没有超时。

当触发空闲超时时，套接字将收到'timeout' 事件，但连接不会被切断。用户必须手动调用 socket.end()或socket.destroy()来结束连接。

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
}); copy

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

可选的callback参数将添加为'timeout'事件的一次性侦听器 。

socket.timeout#

• <数字> | <未定义>

由socket.setTimeout()设置的套接字超时（以毫秒为单位）。如果未设置超时，则为undefined 。

socket.unref()#

• 返回：<net.Socket>套接字本身。

如果这是事件系统中唯一事件的套接字，则在套接字上调用unref()将允许程序退出。如果套接字已经是unref ed，则再次调用 unref()将不起作用。

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

• data <字符串> | <缓冲区> | <Uint8Array>
• encoding <string>仅当数据为string时使用。默认值： utf8。
• callback <函数>
• 返回：<布尔值>

在套接字上发送数据。第二个参数指定字符串情况下的编码。它默认为 UTF8 编码。

如果整个数据已成功刷新到内核缓冲区，则返回true 。如果全部或部分数据已在用户内存中排队， 则返回false 。当缓冲区再次空闲时，将发出'drain' 。

可选的callback参数将在数据最终写出时执行，但可能不会立即执行。

有关详细信息，请参阅Writable Stream write()方法。

socket.readyState#

• <字符串>

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

• 如果流正在连接socket.readyState则为opening。
• 如果流可读可写，则为open。
• 如果流可读但不可写，则为readOnly。
• 如果流不可读写，则为writeOnly。

net.connect()#

别名为 net.createConnection()。

可能的签名：

• net.connect(options[, connectListener])
• net.connect(path[, connectListener])用于IPC 连接。
• net.connect(port[, host][, connectListener]) 用于 TCP 连接。

net.connect(options[, connectListener])#

• options <对象>
• connectListener <函数>
• 返回：<net.Socket>

别名为 net.createConnection(options[, connectListener])。

net.connect(path[, connectListener])#

• path <字符串>
• connectListener <函数>
• 返回：<net.Socket>

别名为 net.createConnection(path[, connectListener])。

net.connect(port[, host][, connectListener])#

• port <数字>
• host <字符串>
• connectListener <函数>
• 返回：<net.Socket>

别名为 net.createConnection(port[, host][, connectListener])。

net.createConnection()#

工厂函数创建一个新的net.Socket，立即启动与socket.connect()的连接，然后返回启动连接的net.Socket 。

建立连接后，将在返回的套接字上发出'connect'事件。最后一个参数connectListener（如果提供）将被添加为'connect'事件的侦听器Once。

可能的签名：

• net.createConnection(options[, connectListener])
• net.createConnection(path[, connectListener]) 用于IPC连接。
• net.createConnection(port[, host][, connectListener]) 用于 TCP 连接。

net.connect()函数是该函数的别名。

net.createConnection(options[, connectListener])#

• options <对象>必需。将传递给 new net.Socket([options])调用和 socket.connect(options[, connectListener]) 方法。
• connectListener <Function> net.createConnection()函数的公共参数 。如果提供，将被添加为返回套接字上的'connect'事件的侦听器一次。
• 返回：<net.Socket>用于启动连接的新创建的套接字。

有关可用选项，请参阅 new net.Socket([options]) 和socket.connect(options[, connectListener])。

其他选项：

• timeout <number>如果设置，将用于 在创建套接字之后、启动连接之前调用socket.setTimeout(timeout) 。

以下是net.createServer()部分中描述的 echo 服务器客户端示例：

const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
}); copy

要连接到套接字/tmp/echo.sock：

const client = net.createConnection({ path: '/tmp/echo.sock' }); copy

net.createConnection(path[, connectListener])#

• path <string>套接字应连接到的路径。将传递给 socket.connect(path[, connectListener])。请参阅识别 IPC 连接的路径。
• connectListener <Function> net.createConnection()函数的公共参数 ，发起套接字上的'connect'事件的“一次”侦听器 。将传递给 socket.connect(path[, connectListener])。
• 返回：<net.Socket>用于启动连接的新创建的套接字。

发起IPC连接。

此函数创建一个新的net.Socket，并将所有选项设置为默认值，立即启动与 socket.connect(path[, connectListener])的连接，然后返回启动连接的net.Socket 。

net.createConnection(port[, host][, connectListener])#

• port <number>套接字应连接到的端口。将传递给 socket.connect(port[, host][, connectListener])。
• host <string>套接字应连接到的主机。将传递给 socket.connect(port[, host][, connectListener])。 默认值： 'localhost'。
• connectListener <Function> net.createConnection()函数的公共参数 ，启动套接字上的'connect'事件的“一次”侦听器 。将传递给 socket.connect(port[, host][, connectListener])。
• 返回：<net.Socket>用于启动连接的新创建的套接字。

启动 TCP 连接。

此函数创建一个新的net.Socket，并将所有选项设置为默认值，立即启动与 socket.connect(port[, host][, connectListener])的连接，然后返回启动连接的net.Socket 。

net.createServer([options][, connectionListener])#

• options <对象>

  • allowHalfOpen <boolean>如果设置为false，那么当可读端结束时，套接字将自动结束可写端。 默认值： false。
  • highWaterMark <number>（可选）覆盖所有net.Socket的 readableHighWaterMark和writableHighWaterMark。 默认值：请参阅stream.getDefaultHighWaterMark()。
  • pauseOnConnect <boolean>指示套接字是否应在传入连接上暂停。默认值： false。
  • noDelay <boolean>如果设置为true，则在收到新的传入连接后立即禁用 Nagle 算法。默认值： false。
  • keepAlive <boolean>如果设置为true，则在收到新的传入连接后立即启用套接字上的保持事件功能，类似于 socket.setKeepAlive([enable][, initialDelay])。 默认值： false。
  • keepAliveInitialDelay <number>如果设置为正数，则设置在空闲套接字上发送第一个保活探测之​​前的初始延迟。默认值： 0。

• connectionListener <Function>自动设置为 'connection'事件的监听器。

• 返回：<net.Server>

创建新的 TCP 或IPC服务器。

如果allowHalfOpen设置为true ，当套接字的另一端发出传输结束信号时，服务器只会在socket.end()时发回传输结束信号被显式调用。例如，在 TCP 上下文中，当收到 FIN 数据包时，仅当显式调用socket.end()时才会发回 FIN 数据包。在此之前，连接处于半关闭状态（不可读但仍可写）。有关详细信息，请参阅'end' 事件和RFC 1122 （第 4.2.2.13 节）。

如果pauseOnConnect设置为true，则与每个传入连接关联的套接字将被暂停，并且不会从其句柄中读取任何数据。这允许在进程之间传递连接，而原始进程不会读取任何数据。要开始从暂停的套接字读取数据，请调用 socket.resume()。

服务器可以是 TCP 服务器或IPC服务器，具体取决于它的用途。 listen()。

以下是侦听端口 8124 上的连接的 TCP 回显服务器的示例：

const net = require('node:net');
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
}); copy

使用telnet进行测试：

$ telnet localhost 8124 copy

监听套接字/tmp/echo.sock：

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
}); copy

使用nc连接到 Unix 域套接字服务器：

$ nc -U /tmp/echo.sock copy

net.getDefaultAutoSelectFamily()#

获取socket.connect(options)的autoSelectFamily 选项的当前默认值。

• 返回：<boolean> autoSelectFamily选项的当前默认值。

net.setDefaultAutoSelectFamily(value)#

设置socket.connect(options)的autoSelectFamily 选项的默认值。

• value <boolean> 新的默认值。初始默认值为false。

net.getDefaultAutoSelectFamilyAttemptTimeout()#

获取socket.connect(options)的autoSelectFamilyAttemptTimeout 选项的当前默认值。

• 返回：<number> autoSelectFamilyAttemptTimeout选项的当前默认值。

net.setDefaultAutoSelectFamilyAttemptTimeout(value)#

设置socket.connect(options)的autoSelectFamilyAttemptTimeout 选项的默认值。

• value <number> 新的默认值，必须是正数。如果数字小于10，则使用值10插入。初始默认值为250。

net.isIP(input)#

• input <字符串>
• 返回：<整数>

如果input是 IPv6 地址，则返回6。如果input是采用点十进制表示法且不带前导零的IPv4 地址，则返回4。否则，返回 0。

net.isIP('::1'); // returns 6
net.isIP('127.0.0.1'); // returns 4
net.isIP('127.000.000.001'); // returns 0
net.isIP('127.0.0.1/24'); // returns 0
net.isIP('fhqwhgads'); // returns 0 copy

net.isIPv4(input)#

• input <字符串>
• 返回：<布尔值>

如果input是采用点十进制表示法且不带前导零的IPv4 地址，则返回true。否则，返回false。

net.isIPv4('127.0.0.1'); // returns true
net.isIPv4('127.000.000.001'); // returns false
net.isIPv4('127.0.0.1/24'); // returns false
net.isIPv4('fhqwhgads'); // returns false copy

net.isIPv6(input)#

• input <字符串>
• 返回：<布尔值>

如果input是 IPv6 地址，则返回true。否则，返回false。

net.isIPv6('::1'); // returns true
net.isIPv6('fhqwhgads'); // returns false copy