Node.js v25.0.0 文档
- Node.js v25.0.0
-
目录
- 网络
- IPC 支持
- 类:
net.BlockList
- 类:
net.SocketAddress
- 类:
net.Server
new net.Server([options][, connectionListener])
- 事件:
'close'
- 事件:
'connection'
- 事件:
'error'
- 事件:
'listening'
- 事件:
'drop'
server.address()
server.close([callback])
server[Symbol.asyncDispose]()
server.getConnections(callback)
server.listen()
server.listening
server.maxConnections
server.dropMaxConnection
server.ref()
server.unref()
- 类:
net.Socket
new net.Socket([options])
- 事件:
'close'
- 事件:
'connect'
- 事件:
'connectionAttempt'
- 事件:
'connectionAttemptFailed'
- 事件:
'connectionAttemptTimeout'
- 事件:
'data'
- 事件:
'drain'
- 事件:
'end'
- 事件:
'error'
- 事件:
'lookup'
- 事件:
'ready'
- 事件:
'timeout'
socket.address()
socket.autoSelectFamilyAttemptedAddresses
socket.bufferSize
socket.bytesRead
socket.bytesWritten
socket.connect()
socket.connecting
socket.destroy([error])
socket.destroyed
socket.destroySoon()
socket.end([data[, encoding]][, callback])
socket.localAddress
socket.localPort
socket.localFamily
socket.pause()
socket.pending
socket.ref()
socket.remoteAddress
socket.remoteFamily
socket.remotePort
socket.resetAndDestroy()
socket.resume()
socket.setEncoding([encoding])
socket.setKeepAlive([enable][, initialDelay])
socket.setNoDelay([noDelay])
socket.setTimeout(timeout[, callback])
socket.timeout
socket.unref()
socket.write(data[, encoding][, callback])
socket.readyState
net.connect()
net.createConnection()
net.createServer([options][, connectionListener])
net.getDefaultAutoSelectFamily()
net.setDefaultAutoSelectFamily(value)
net.getDefaultAutoSelectFamilyAttemptTimeout()
net.setDefaultAutoSelectFamilyAttemptTimeout(value)
net.isIP(input)
net.isIPv4(input)
net.isIPv6(input)
- 网络
-
索引
- 断言测试
- 异步上下文跟踪
- 异步钩子
- 缓冲区
- C++ 插件
- 使用 Node-API 的 C/C++ 插件
- C++ 嵌入器 API
- 子进程
- 集群
- 命令行选项
- 控制台
- 加密
- 调试器
- 已弃用的 API
- 诊断通道
- DNS
- 域
- 环境变量
- 错误
- 事件
- 文件系统
- 全局对象
- HTTP
- HTTP/2
- HTTPS
- 检查器
- 国际化
- 模块:CommonJS 模块
- 模块:ECMAScript 模块
- 模块:
node:module
API - 模块:包
- 模块:TypeScript
- 网络
- 操作系统
- 路径
- 性能钩子
- 权限
- 进程
- Punycode
- 查询字符串
- 逐行读取
- REPL
- 报告
- 单一可执行文件应用
- SQLite
- 流
- 字符串解码器
- 测试运行器
- 定时器
- TLS/SSL
- 跟踪事件
- TTY
- UDP/数据报
- URL
- 实用工具
- V8
- 虚拟机
- WASI
- Web Crypto API
- Web Streams API
- 工作线程
- Zlib
- 其他版本
- 选项
Net#
源代码: lib/net.js
node:net
模块提供了一个异步网络 API,用于创建基于流的 TCP 或 IPC 服务器 (net.createServer()
) 和客户端 (net.createConnection()
)。
它可以通过以下方式访问
import net from 'node:net';
const net = require('node:net');
IPC 支持#
node:net
模块在 Windows 上通过命名管道支持 IPC,在其他操作系统上通过 Unix 域套接字支持 IPC。
识别 IPC 连接的路径#
net.connect()
、net.createConnection()
、server.listen()
和 socket.connect()
接受一个 path
参数来标识 IPC 端点。
在 Unix 上,本地域也称为 Unix 域。路径是一个文件系统路径名。当路径名长度大于 sizeof(sockaddr_un.sun_path)
的长度时,会抛出错误。典型值在 Linux 上是 107 字节,在 macOS 上是 103 字节。如果一个 Node.js API 抽象创建了 Unix 域套接字,它也会取消链接该 Unix 域套接字。例如,net.createServer()
可能会创建一个 Unix 域套接字,而 server.close()
会取消链接它。但如果用户在这些抽象之外创建了 Unix 域套接字,用户将需要自己移除它。当 Node.js API 创建了一个 Unix 域套接字但程序随后崩溃时,也适用同样的情况。简而言之,一个 Unix 域套接字将在文件系统中可见,并会一直存在直到被取消链接。在 Linux 上,你可以通过在路径开头添加 \0
来使用 Unix 抽象套接字,例如 \0abstract
。Unix 抽象套接字的路径在文件系统中不可见,当所有对该套接字的打开引用都关闭时,它将自动消失。
在 Windows 上,本地域是使用命名管道实现的。路径必须指向 \\?\pipe\
或 \\.\pipe\
中的一个条目。允许任何字符,但后者可能会对管道名称进行一些处理,例如解析 ..
序列。尽管看起来可能不是这样,但管道命名空间是扁平的。管道将不会持久化。当对它们的最后一个引用关闭时,它们会被移除。与 Unix 域套接字不同,Windows 会在所属进程退出时关闭并移除管道。
JavaScript 字符串转义要求路径使用额外的反斜杠进行转义,例如
net.createServer().listen(
path.join('\\\\?\\pipe', process.cwd(), 'myctl'));
类:net.BlockList
#
BlockList
对象可以与某些网络 API 一起使用,以指定禁用对特定 IP 地址、IP 范围或 IP 子网的入站或出站访问的规则。
blockList.addAddress(address[, type])
#
address
<string> | <net.SocketAddress> 一个 IPv4 或 IPv6 地址。type
<string>'ipv4'
或'ipv6'
。默认值:'ipv4'
。
添加一条规则以阻止给定的 IP 地址。
blockList.addRange(start, end[, type])
#
start
<string> | <net.SocketAddress> 范围中的起始 IPv4 或 IPv6 地址。end
<string> | <net.SocketAddress> 范围中的结束 IPv4 或 IPv6 地址。type
<string>'ipv4'
或'ipv6'
。默认值:'ipv4'
。
添加一条规则以阻止从 start
(包含) 到 end
(包含) 的 IP 地址范围。
blockList.addSubnet(net, prefix[, type])
#
net
<string> | <net.SocketAddress> 网络 IPv4 或 IPv6 地址。prefix
<number> CIDR 前缀位数。对于 IPv4,此值必须在0
和32
之间。对于 IPv6,此值必须在0
和128
之间。type
<string>'ipv4'
或'ipv6'
。默认值:'ipv4'
。
添加一条规则以阻止指定为子网掩码的 IP 地址范围。
blockList.check(address[, type])
#
address
<string> | <net.SocketAddress> 要检查的 IP 地址type
<string>'ipv4'
或'ipv6'
。默认值:'ipv4'
。- 返回:<boolean>
如果给定的 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
blockList.fromJSON(value)
#
const blockList = new net.BlockList();
const data = [
'Subnet: IPv4 192.168.1.0/24',
'Address: IPv4 10.0.0.5',
'Range: IPv4 192.168.2.1-192.168.2.10',
'Range: IPv4 10.0.0.1-10.0.0.10',
];
blockList.fromJSON(data);
blockList.fromJSON(JSON.stringify(data));
value
Blocklist.rules
类:net.SocketAddress
#
new net.SocketAddress([options])
#
SocketAddress.parse(input)
#
input
<string> 包含 IP 地址和可选端口的输入字符串,例如123.1.2.3:1234
或[1::1]:1234
。- 返回:<net.SocketAddress> 如果解析成功,则返回一个
SocketAddress
。否则返回undefined
。
类:net.Server
#
- 继承自:<EventEmitter>
这个类用于创建一个 TCP 或 IPC 服务器。
new net.Server([options][, connectionListener])
#
options
<Object> 参见net.createServer([options][, connectionListener])
。connectionListener
<Function> 自动设置为'connection'
事件的监听器。- 返回:<net.Server>
net.Server
是一个 EventEmitter
,具有以下事件
事件:'close'
#
在服务器关闭时触发。如果存在连接,此事件直到所有连接结束后才会触发。
事件:'error'
#
- 类型:<Error>
当发生错误时触发。与 net.Socket
不同,除非手动调用 server.close()
,否则 'close'
事件将不会在此事件之后直接触发。请参见 server.listen()
讨论中的示例。
事件:'listening'
#
在调用 server.listen()
后服务器被绑定时触发。
事件:'drop'
#
当连接数达到 server.maxConnections
的阈值时,服务器将丢弃新连接并触发 'drop'
事件。如果它是一个 TCP 服务器,则参数如下,否则参数为 undefined
。
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());
});
在 'listening'
事件触发之前或调用 server.close()
之后,server.address()
返回 null
。
server.close([callback])
#
callback
<Function> 在服务器关闭时调用。- 返回:<net.Server>
停止服务器接受新连接并保持现有连接。此函数是异步的,当所有连接都结束并且服务器发出 'close'
事件时,服务器最终关闭。可选的 callback
将在 'close'
事件发生时被调用一次。与该事件不同,如果服务器在关闭时未打开,它将以一个 Error
作为其唯一参数被调用。
server[Symbol.asyncDispose]()
#
调用 server.close()
并返回一个 Promise,该 Promise 在服务器关闭时兑现。
server.getConnections(callback)
#
callback
<Function>- 返回:<net.Server>
异步获取服务器上的并发连接数。在套接字被发送到子进程时也有效。
回调函数应接受两个参数 err
和 count
。
server.listen()
#
启动一个服务器来监听连接。一个 net.Server
可以是 TCP 或 IPC 服务器,这取决于它监听的对象。
可能的签名
server.listen(handle[, backlog][, callback])
server.listen(options[, callback])
server.listen(path[, backlog][, callback])
用于 IPC 服务器server.listen([port[, host[, backlog]]][, callback])
用于 TCP 服务器
此函数是异步的。当服务器开始监听时,将触发 '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);
}
});
server.listen(handle[, backlog][, callback])
#
handle
<Object>backlog
<number>server.listen()
函数的通用参数callback
<Function>- 返回:<net.Server>
在一个已经绑定到端口、Unix 域套接字或 Windows 命名管道的给定 handle
上启动服务器监听连接。
handle
对象可以是一个服务器、一个套接字(任何带有底层 _handle
成员的东西),或者一个带有一个有效文件描述符的 fd
成员的对象。
在 Windows 上不支持监听文件描述符。
server.listen(options[, callback])
#
options
<Object> 必需。支持以下属性backlog
<number>server.listen()
函数的通用参数。exclusive
<boolean> 默认值:false
host
<string>ipv6Only
<boolean> 对于 TCP 服务器,将ipv6Only
设置为true
将禁用双栈支持,即绑定到主机::
不会导致0.0.0.0
被绑定。默认值:false
。reusePort
<boolean> 对于 TCP 服务器,将reusePort
设置为true
允许同一主机上的多个套接字绑定到同一个端口。传入的连接由操作系统分发到监听的套接字。此选项仅在某些平台上可用,例如 Linux 3.9+、DragonFlyBSD 3.6+、FreeBSD 12.0+、Solaris 11.4 和 AIX 7.2.5+。默认值:false
。path
<string> 如果指定了port
,则此项将被忽略。参见 识别 IPC 连接的路径。port
<number>readableAll
<boolean> 对于 IPC 服务器,使管道对所有用户可读。默认值:false
。signal
<AbortSignal> 可用于关闭监听服务器的 AbortSignal。writableAll
<boolean> 对于 IPC 服务器,使管道对所有用户可写。默认值:false
。
callback
<Function> 函数。- 返回:<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,
});
当 exclusive
为 true
且底层句柄是共享的时,可能会有多个工作进程使用不同的 backlog 查询句柄。在这种情况下,将使用传递给主进程的第一个 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();
server.listen(path[, backlog][, callback])
#
path
<string> 服务器应该监听的路径。参见 识别 IPC 连接的路径。backlog
<number>server.listen()
函数的通用参数。callback
<Function>。- 返回:<net.Server>
启动一个 IPC 服务器,在给定的 path
上监听连接。
server.listen([port[, host[, backlog]]][, callback])
#
port
<number>host
<string>backlog
<number>server.listen()
函数的通用参数。callback
<Function>。- 返回:<net.Server>
在给定的 port
和 host
上启动一个 TCP 服务器以监听连接。
如果省略 port
或其值为 0,操作系统将分配一个任意未使用的端口,该端口可以在 'listening'
事件触发后通过 server.address().port
获取。
如果省略 host
,当 IPv6 可用时,服务器将接受未指定的 IPv6 地址(::
)上的连接,否则接受未指定的 IPv4 地址(0.0.0.0
)上的连接。
在大多数操作系统中,监听未指定的 IPv6 地址 (::
) 可能会导致 net.Server
也在未指定的 IPv4 地址 (0.0.0.0
) 上监听。
server.maxConnections
#
- 类型:<integer>
当连接数达到 server.maxConnections
阈值时
-
如果进程不是在集群模式下运行,Node.js 将关闭连接。
-
如果进程在集群模式下运行,Node.js 默认会将连接路由到另一个工作进程。要改为关闭连接,请将 [
server.dropMaxConnection
][] 设置为true
。
不建议在套接字通过 child_process.fork()
发送给子进程后使用此选项。
server.dropMaxConnection
#
- 类型:<boolean>
将此属性设置为 true
,以便在连接数达到 [server.maxConnections
][] 阈值时开始关闭连接。此设置仅在集群模式下有效。
server.ref()
#
- 返回:<net.Server>
与 unref()
相反,对一个先前被 unref
的服务器调用 ref()
将不会让程序在它是唯一剩下的服务器时退出(默认行为)。如果服务器已经被 ref
,再次调用 ref()
将没有效果。
server.unref()
#
- 返回:<net.Server>
在服务器上调用 unref()
将允许程序在事件系统中这是唯一活动的服务器时退出。如果服务器已经被 unref
,再次调用 unref()
将没有效果。
类:net.Socket
#
这个类是 TCP 套接字或流式 IPC 端点(在 Windows 上使用命名管道,在其他系统上使用 Unix 域套接字)的抽象。它也是一个 EventEmitter
。
net.Socket
可以由用户创建并直接用于与服务器交互。例如,它由 net.createConnection()
返回,因此用户可以用它来与服务器通信。
它也可以由 Node.js 创建并在接收到连接时传递给用户。例如,它被传递给在 net.Server
上触发的 'connection'
事件的监听器,因此用户可以用它来与客户端交互。
new net.Socket([options])
#
options
<Object> 可用选项有allowHalfOpen
<boolean> 如果设置为false
,则当可读端结束时,套接字将自动结束可写端。详情请参阅net.createServer()
和'end'
事件。默认值:false
。fd
<number> 如果指定,则包装一个具有给定文件描述符的现有套接字,否则将创建一个新套接字。onread
<Object> 如果指定,传入数据将存储在单个buffer
中,并在数据到达套接字时传递给提供的callback
。这将导致流功能不提供任何数据。套接字将像往常一样触发'error'
、'end'
和'close'
等事件。像pause()
和resume()
这样的方法也将按预期工作。buffer
<Buffer> | <Uint8Array> | <Function> 一个可重用的内存块,用于存储传入数据,或者是一个返回此类内存块的函数。callback
<Function> 这个函数会为每个传入的数据块调用。它会接收两个参数:写入buffer
的字节数和对buffer
的引用。从此函数返回false
将隐式地pause()
套接字。此函数将在全局上下文中执行。
readable
<boolean> 当传递fd
时允许在套接字上读取,否则忽略。默认值:false
。signal
<AbortSignal> 可用于销毁套接字的 Abort 信号。writable
<boolean> 当传递fd
时允许在套接字上写入,否则忽略。默认值:false
。
- 返回:<net.Socket>
创建一个新的套接字对象。
事件:'close'
#
hadError
<boolean> 如果套接字有传输错误,则为true
。
一旦套接字完全关闭就会触发。参数 hadError
是一个布尔值,表示套接字是否由于传输错误而关闭。
事件:'connect'
#
当套接字连接成功建立时触发。参见 net.createConnection()
。
事件:'connectionAttempt'
#
ip
<string> 套接字正在尝试连接的 IP 地址。port
<number> 套接字正在尝试连接的端口。family
<number> IP 的地址族。IPv6 为6
,IPv4 为4
。
当开始新的连接尝试时触发。如果在 socket.connect(options)
中启用了地址族自动选择算法,此事件可能会触发多次。
事件:'connectionAttemptFailed'
#
ip
<string> 套接字尝试连接的 IP。port
<number> 套接字尝试连接的端口。family
<number> IP 的地址族。IPv6 为6
,IPv4 为4
。error
<Error> 与失败相关的错误。
当连接尝试失败时发出。如果在 socket.connect(options)
中启用了地址族自动选择算法,此事件可能会被发出多次。
事件:'connectionAttemptTimeout'
#
当连接尝试超时时触发。仅当在 socket.connect(options)
中启用了地址族自动选择算法时才会触发此事件(并且可能会触发多次)。
事件:'data'
#
当接收到数据时触发。参数 data
将是一个 Buffer
或 String
。数据的编码由 socket.setEncoding()
设置。
如果当一个 Socket
触发 'data'
事件时没有监听器,数据将会丢失。
事件:'end'
#
当套接字的另一端发出传输结束信号时触发,从而结束套接字的可读端。
默认情况下 (allowHalfOpen
为 false
),套接字会发回一个传输结束数据包,并在写完其待处理的写队列后销毁其文件描述符。但是,如果 allowHalfOpen
设置为 true
,套接字将不会自动 end()
其可写端,允许用户写入任意数量的数据。用户必须显式调用 end()
来关闭连接(即发送一个 FIN 数据包)。
事件:'lookup'
#
在解析主机名之后、连接之前触发。不适用于 Unix 套接字。
err
<Error> | <null> 错误对象。参见dns.lookup()
。address
<string> IP 地址。family
<number> | <null> 地址类型。参见dns.lookup()
。host
<string> 主机名。
socket.address()
#
- 返回:<Object>
返回由操作系统报告的套接字绑定的 address
、地址 family
名称和 port
:{ port: 12346, family: 'IPv4', address: '127.0.0.1' }
socket.autoSelectFamilyAttemptedAddresses
#
- 类型:<string[]>
此属性仅在 socket.connect(options)
中启用了地址族自动选择算法时才存在,它是一个包含已尝试过的地址的数组。
每个地址都是 $IP:$PORT
形式的字符串。如果连接成功,则最后一个地址是套接字当前连接的地址。
socket.bufferSize
#
writable.writableLength
。- 类型:<integer>
此属性显示了为写入而缓冲的字符数。缓冲区可能包含编码后长度未知的字符串。所以这个数字只是缓冲区中字节数的近似值。
net.Socket
的特性是 socket.write()
总是有效的。这是为了帮助用户快速上手。计算机不可能总是跟得上写入套接字的数据量。网络连接可能太慢。Node.js 会在内部将写入套接字的数据排队,并在可能的时候通过网络发送出去。
这种内部缓冲的结果是内存可能会增长。遇到 bufferSize
变大或持续增长的用户应尝试使用 socket.pause()
和 socket.resume()
在其程序中“节流”数据流。
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'
事件的一次性监听器。
此函数只应用于在 'close'
事件触发后重新连接套接字,否则可能导致未定义行为。
socket.connect(options[, connectListener])
#
options
<Object>connectListener
<Function>socket.connect()
方法的通用参数。将作为'connect'
事件的一次性监听器添加。- 返回:<net.Socket> 套接字本身。
在给定的套接字上发起连接。通常不需要此方法,套接字应该通过 net.createConnection()
创建和打开。仅在实现自定义套接字时使用此方法。
对于 TCP 连接,可用的 options
有
autoSelectFamily
<boolean>: 如果设置为true
,则启用一个大致实现 RFC 8305 第 5 节的地址族自动检测算法。传递给 lookup 的all
选项设置为true
,套接字会按顺序尝试连接所有获取到的 IPv6 和 IPv4 地址,直到建立连接。首先尝试第一个返回的 AAAA 地址,然后是第一个返回的 A 地址,然后是第二个返回的 AAAA 地址,依此类推。每次连接尝试(除了最后一次)都会被给予autoSelectFamilyAttemptTimeout
选项指定的时间,然后超时并尝试下一个地址。如果family
选项不是0
或设置了localAddress
,则忽略此选项。如果至少有一个连接成功,则不会触发连接错误。如果所有连接尝试都失败,则会触发一个包含所有失败尝试的AggregateError
。默认值:net.getDefaultAutoSelectFamily()
。autoSelectFamilyAttemptTimeout
<number>: 在使用autoSelectFamily
选项时,等待连接尝试完成再尝试下一个地址的时间(以毫秒为单位)。如果设置为小于10
的正整数,则将使用值10
。默认值:net.getDefaultAutoSelectFamilyAttemptTimeout()
。family
<number>:IP 协议栈版本。必须是4
、6
或0
。值0
表示允许 IPv4 和 IPv6 地址。默认值:0
。hints
<number> 可选的dns.lookup()
提示。host
<string> 套接字应连接的主机。默认值:'localhost'
。keepAlive
<boolean> 如果设置为true
,则在连接建立后立即在套接字上启用 keep-alive 功能,类似于在socket.setKeepAlive()
中所做的。默认值:false
。keepAliveInitialDelay
<number> 如果设置为正数,它将设置在空闲套接字上发送第一个 keepalive 探测之前的初始延迟。默认值:0
。localAddress
<string> 套接字应从中连接的本地地址。localPort
<number> 套接字应从中连接的本地端口。lookup
<Function> 自定义查找函数。默认值:dns.lookup()
。noDelay
<boolean> 如果设置为true
,则在套接字建立后立即禁用 Nagle 算法。默认值:false
。port
<number> 必需。套接字应连接的端口。blockList
<net.BlockList>blockList
可用于禁用对特定 IP 地址、IP 范围或 IP 子网的出站访问。
对于 IPC 连接,可用的 options
有
path
<string> 必需。客户端应连接的路径。参见 识别 IPC 连接的路径。如果提供此项,则上述 TCP 特定选项将被忽略。
socket.connect(path[, connectListener])
#
path
<string> 客户端应该连接的路径。参见 识别 IPC 连接路径。connectListener
<Function>socket.connect()
方法的通用参数。将作为'connect'
事件的一次性监听器添加。- 返回:<net.Socket> 套接字本身。
在给定的套接字上发起一个 IPC 连接。
是 socket.connect(options[, connectListener])
的别名,其中 options
为 { path: path }
。
socket.connect(port[, host][, connectListener])
#
port
<number> 客户端应连接的端口。host
<string> 客户端应连接的主机。connectListener
<Function>socket.connect()
方法的通用参数。将作为'connect'
事件的一次性监听器添加。- 返回:<net.Socket> 套接字本身。
在给定的套接字上发起一个 TCP 连接。
是 socket.connect(options[, connectListener])
的别名,其中 options
为 {port: port, host: host}
。
socket.connecting
#
- 类型:<boolean>
如果为 true
,表示 socket.connect(options[, connectListener])
已被调用但尚未完成。它将保持为 true
直到套接字连接成功,然后被设置为 false
并触发 'connect'
事件。请注意,socket.connect(options[, connectListener])
的回调函数是 'connect'
事件的监听器。
socket.destroy([error])
#
error
<Object>- 返回:<net.Socket>
确保此套接字上不再发生 I/O 活动。销毁流并关闭连接。
更多详情请参阅 writable.destroy()
。
socket.destroySoon()
#
在所有数据写入后销毁套接字。如果 'finish'
事件已经被触发,套接字将立即被销毁。如果套接字仍然可写,它会隐式调用 socket.end()
。
socket.end([data[, encoding]][, callback])
#
data
<string> | <Buffer> | <Uint8Array>encoding
<string> 仅当数据为string
时使用。默认值:'utf8'
。callback
<Function> 套接字完成时的可选回调。- 返回:<net.Socket> 套接字本身。
半关闭套接字。即,它发送一个 FIN 包。服务器可能仍会发送一些数据。
更多详情请参阅 writable.end()
。
socket.localAddress
#
- 类型:<string>
远程客户端连接的本地 IP 地址的字符串表示。例如,在一个监听 '0.0.0.0'
的服务器上,如果一个客户端连接到 '192.168.1.1'
,那么 socket.localAddress
的值将是 '192.168.1.1'
。
socket.pending
#
- 类型:<boolean>
如果套接字尚未连接,则此值为 true
,原因可能是 .connect()
尚未被调用,或者它仍在连接过程中(参见 socket.connecting
)。
socket.ref()
#
- 返回:<net.Socket> 套接字本身。
与 unref()
相反,在一个之前被 unref
的套接字上调用 ref()
将不会让程序在它是唯一剩下的套接字时退出(默认行为)。如果套接字已经被 ref
,再次调用 ref
将没有效果。
socket.remoteAddress
#
- 类型:<string>
远程 IP 地址的字符串表示。例如,'74.125.127.100'
或 '2001:4860:a005::68'
。如果套接字被销毁(例如,如果客户端断开连接),该值可能为 undefined
。
socket.remoteFamily
#
- 类型:<string>
远程 IP 协议族的字符串表示。'IPv4'
或 'IPv6'
。如果套接字被销毁(例如,如果客户端断开连接),该值可能为 undefined
。
socket.resetAndDestroy()
#
- 返回:<net.Socket>
通过发送 RST 数据包关闭 TCP 连接并销毁流。如果此 TCP 套接字处于连接状态,它将在连接后发送 RST 数据包并销毁此 TCP 套接字。否则,它将调用带有 ERR_SOCKET_CLOSED
错误的 socket.destroy
。如果这不是一个 TCP 套接字(例如,一个管道),调用此方法将立即抛出 ERR_INVALID_HANDLE_TYPE
错误。
socket.setEncoding([encoding])
#
encoding
<string>- 返回:<net.Socket> 套接字本身。
为套接字设置编码,作为 Readable Stream。更多信息请参见 readable.setEncoding()
。
socket.setKeepAlive([enable][, initialDelay])
#
enable
<boolean> 默认值:false
initialDelay
<number> 默认值:0
- 返回:<net.Socket> 套接字本身。
启用/禁用 keep-alive 功能,并可选择设置在空闲套接字上发送第一个 keepalive 探测之前的初始延迟。
设置 initialDelay
(以毫秒为单位)来设置从接收到最后一个数据包到第一个 keepalive 探测之间的延迟。为 initialDelay
设置 0
将使其值保持默认(或先前)设置不变。
启用 keep-alive 功能将设置以下套接字选项
SO_KEEPALIVE=1
TCP_KEEPIDLE=initialDelay
TCP_KEEPCNT=10
TCP_KEEPINTVL=1
socket.setNoDelay([noDelay])
#
noDelay
<boolean> 默认值:true
- 返回:<net.Socket> 套接字本身。
启用/禁用 Nagle 算法。
当创建 TCP 连接时,它将启用 Nagle 算法。
Nagle 算法在数据通过网络发送前会延迟数据。它试图以牺牲延迟为代价来优化吞吐量。
为 noDelay
传入 true
或不传入参数将为套接字禁用 Nagle 算法。为 noDelay
传入 false
将启用 Nagle 算法。
socket.setTimeout(timeout[, callback])
#
timeout
<number>callback
<Function>- 返回:<net.Socket> 套接字本身。
设置套接字在不活动 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
#
- 类型:<number> | <undefined>
由 socket.setTimeout()
设置的套接字超时时间(以毫秒为单位)。如果未设置超时,则为 undefined
。
socket.unref()
#
- 返回:<net.Socket> 套接字本身。
在套接字上调用 unref()
将允许程序在事件系统中这是唯一活动的套接字时退出。如果套接字已经被 unref
,再次调用 unref()
将没有效果。
socket.write(data[, encoding][, callback])
#
data
<string> | <Buffer> | <Uint8Array>encoding
<string> 仅在数据为string
时使用。默认值:utf8
。callback
<Function>- 返回:<boolean>
在套接字上发送数据。第二个参数在数据是字符串时指定编码。它默认为 UTF8 编码。
如果全部数据已成功刷新到内核缓冲区,则返回 true
。如果全部或部分数据已在用户内存中排队,则返回 false
。当缓冲区再次空闲时,将触发 'drain'
事件。
可选的 callback
参数将在数据最终写出时执行,这可能不会立即发生。
更多信息请参见 Writable
流的 write()
方法。
net.connect()
#
可能的签名
net.connect(options[, connectListener])
net.connect(path[, connectListener])
用于 IPC 连接。net.connect(port[, host][, connectListener])
用于 TCP 连接。
net.connect(options[, connectListener])
#
options
<Object>connectListener
<Function>- 返回:<net.Socket>
net.connect(path[, connectListener])
#
path
<string>connectListener
<Function>- 返回:<net.Socket>
net.connect(port[, host][, connectListener])
#
port
<number>host
<string>connectListener
<Function>- 返回:<net.Socket>
net.createConnection()
#
一个工厂函数,它创建一个新的 net.Socket
,立即用 socket.connect()
发起连接,然后返回开始连接的 net.Socket
。
当连接建立时,返回的套接字上会触发一个 'connect'
事件。最后一个参数 connectListener
(如果提供)将被添加为 'connect'
事件的一次性监听器。
可能的签名
net.createConnection(options[, connectListener])
net.createConnection(path[, connectListener])
用于 IPC 连接。net.createConnection(port[, host][, connectListener])
用于 TCP 连接。
net.connect()
函数是此函数的别名。
net.createConnection(options[, connectListener])
#
options
<Object> 必需。此对象会同时传递给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()
部分中描述的回显服务器的客户端示例:
import net from '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');
});
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');
});
连接到套接字 /tmp/echo.sock
:
const client = net.createConnection({ path: '/tmp/echo.sock' });
以下是使用 port
和 onread
选项的客户端示例。在这种情况下,onread
选项将仅用于调用 new net.Socket([options])
,而 port
选项将用于调用 socket.connect(options[, connectListener])
。
import net from 'node:net';
import { Buffer } from 'node:buffer';
net.createConnection({
port: 8124,
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));
},
},
});
const net = require('node:net');
net.createConnection({
port: 8124,
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));
},
},
});
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
<Object>allowHalfOpen
<boolean> 如果设置为false
,那么当可读端结束时,套接字将自动结束可写端。默认值:false
。highWaterMark
<number> 可选地覆盖所有net.Socket
的readableHighWaterMark
和writableHighWaterMark
。默认值: 请参阅stream.getDefaultHighWaterMark()
。keepAlive
<boolean> 如果设置为true
,它会在收到新的传入连接后立即在套接字上启用 keep-alive 功能,类似于在socket.setKeepAlive()
中的操作。默认值:false
。keepAliveInitialDelay
<number> 如果设置为正数,它将设置在空闲套接字上发送第一个 keepalive 探测之前的初始延迟。默认值:0
。noDelay
<boolean> 如果设置为true
,它会在收到新的传入连接后立即禁用 Nagle 算法。默认值:false
。pauseOnConnect
<boolean> 指示是否应在传入连接时暂停套接字。默认值:false
。blockList
<net.BlockList>blockList
可用于禁止对特定 IP 地址、IP 范围或 IP 子网的入站访问。如果服务器位于反向代理、NAT 等之后,则此功能不起作用,因为与阻止列表进行比较的地址是代理的地址,或者是 NAT 指定的地址。
-
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()
的对象。
这是一个 TCP 回显服务器的示例,它在 8124 端口上监听连接:
import net from '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');
});
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');
});
使用 telnet
进行测试:
telnet localhost 8124
要监听套接字 /tmp/echo.sock
:
server.listen('/tmp/echo.sock', () => {
console.log('server bound');
});
使用 nc
连接到 Unix 域套接字服务器:
nc -U /tmp/echo.sock
net.getDefaultAutoSelectFamily()
#
获取 socket.connect(options)
的 autoSelectFamily
选项的当前默认值。初始默认值为 true
,除非提供了命令行选项 --no-network-family-autoselection
。
- 返回: <boolean>
autoSelectFamily
选项的当前默认值。
net.setDefaultAutoSelectFamily(value)
#
设置 socket.connect(options)
的 autoSelectFamily
选项的默认值。
value
<boolean> 新的默认值。初始默认值为true
,除非提供了命令行选项--no-network-family-autoselection
。
net.getDefaultAutoSelectFamilyAttemptTimeout()
#
获取 socket.connect(options)
的 autoSelectFamilyAttemptTimeout
选项的当前默认值。初始默认值为 250
或通过命令行选项 --network-family-autoselection-attempt-timeout
指定的值。
- 返回: <number>
autoSelectFamilyAttemptTimeout
选项的当前默认值。
net.setDefaultAutoSelectFamilyAttemptTimeout(value)
#
设置 socket.connect(options)
的 autoSelectFamilyAttemptTimeout
选项的默认值。
value
<number> 新的默认值,必须是正数。如果该数字小于10
,则使用值10
代替。初始默认值为250
或通过命令行选项--network-family-autoselection-attempt-timeout
指定的值。
net.isIP(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
net.isIPv4(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
net.isIPv6(input)
#
如果 input
是 IPv6 地址,则返回 true
。否则,返回 false
。
net.isIPv6('::1'); // returns true
net.isIPv6('fhqwhgads'); // returns false