- assert断言
- async_hooks异步钩子
- async_hooks/context异步上下文
- buffer缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process子进程
- cluster集群
- CLI命令行
- console控制台
- Corepack核心包
- crypto加密
- crypto/webcrypto网络加密
- debugger调试器
- deprecation弃用
- dgram数据报
- diagnostics_channel诊断通道
- dns域名服务器
- domain域
- Error错误
- events事件触发器
- fs文件系统
- global全局变量
- http超文本传输协议
- http2超文本传输协议2.0
- https安全超文本传输协议
- inspector检查器
- Intl国际化
- module模块
- module/cjsCommonJS模块
- module/esmECMAScript模块
- module/package包模块
- net网络
- os操作系统
- path路径
- perf_hooks性能钩子
- permission权限
- policy安全策略
- process进程
- punycode域名代码
- querystring查询字符串
- readline逐行读取
- repl交互式解释器
- report诊断报告
- stream流
- stream/web网络流
- string_decoder字符串解码器
- test测试
- timers定时器
- tls安全传输层
- trace_events跟踪事件
- tty终端
- url网址
- util实用工具
- v8引擎
- vm虚拟机
- wasi网络汇编系统接口
- worker_threads工作线程
- zlib压缩
Node.js v16.19.1 文档
- Node.js 16.19.1
-
►
目录
- net 网络
- IPC 支持
net.BlockList
类net.SocketAddress
类net.Server
类net.Socket
类new net.Socket([options])
'close'
事件'connect'
事件'data'
事件'drain'
事件'end'
事件'error'
事件'lookup'
事件'ready'
事件'timeout'
事件socket.address()
socket.bufferSize
socket.bytesRead
socket.bytesWritten
socket.connect()
socket.connecting
socket.destroy([error])
socket.destroyed
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.isIP(input)
net.isIPv4(input)
net.isIPv6(input)
- net 网络
-
►
索引
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- policy 安全策略
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- ► 其他版本
- 文档搜索
目录
- net 网络
- IPC 支持
net.BlockList
类net.SocketAddress
类net.Server
类net.Socket
类new net.Socket([options])
'close'
事件'connect'
事件'data'
事件'drain'
事件'end'
事件'error'
事件'lookup'
事件'ready'
事件'timeout'
事件socket.address()
socket.bufferSize
socket.bytesRead
socket.bytesWritten
socket.connect()
socket.connecting
socket.destroy([error])
socket.destroyed
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.isIP(input)
net.isIPv4(input)
net.isIPv6(input)
net 网络#
源代码: lib/net.js
node:net
模块提供了异步的网络 API,用于创建基于流的 TCP 或 IPC 服务器 (net.createServer()
) 和客户端 (net.createConnection()
)。
可以使用以下方式访问它:
const net = require('node:net');
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'));
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')); // 打印: true
console.log(blockList.check('10.0.0.3')); // 打印: true
console.log(blockList.check('222.111.111.222')); // 打印: false
// IPv4 地址的 IPv6 表示法有效:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // 打印: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // 打印: true
blockList.rules
#
- 类型: <string[]>
添加到阻止列表的规则列表。
net.SocketAddress
类#
new net.SocketAddress([options])
#
options
<Object>
socketaddress.address
#
- 类型 <string>
socketaddress.family
#
- 类型 <string>
'ipv4'
或'ipv6'
。
socketaddress.flowlabel
#
- 类型 <number>
socketaddress.port
#
- 类型 <number>
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'
事件#
服务器关闭时触发。 如果连接存在,则在所有连接结束之前不会触发此事件。
'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> 传给事件监听器的参数。
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) => {
// 在这里处理错误。
throw err;
});
// 获取任意未使用的端口。
server.listen(() => {
console.log('opened server on', server.address());
});
server.address()
在 'listening'
事件触发之前或调用 server.close()
之后返回 null
。
server.close([callback])
#
callback
<Function> 服务器关闭时调用。- 返回: <net.Server>
停止服务器接受新连接并保持现有连接。
该函数是异步的,当所有连接都结束并且服务器触发 'close'
事件时,则服务器最终关闭。
一旦 'close'
事件发生,则可选的 callback
将被调用。
与该事件不同,如果服务器在关闭时未打开,它将以 Error
作为唯一参数被调用。
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.log('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> 必需的。 支持以下属性:port
<number>host
<string>path
<string> 如果指定了port
,则将被忽略。 请参阅标识 IPC 连接的路径。backlog
<number>server.listen()
函数的通用参数。exclusive
<boolean> 默认值:false
readableAll
<boolean> 对于 IPC 服务器,使管道对所有用户都可读。 默认值:false
。writableAll
<boolean> 对于 IPC 服务器,使管道对所有用户都可写。 默认值:false
。ipv6Only
<boolean> 对于 TCP 服务器,将ipv6Only
设置为true
将禁用双栈支持,即绑定到主机::
不会绑定0.0.0.0
。 默认值:false
。signal
<AbortSignal> 可用于关闭监听服务器的中止信号。
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
。
以 root 身份启动 IPC 服务器可能会导致非特权用户无法访问服务器路径。
使用 readableAll
和 writableAll
将使所有用户都可以访问服务器。
如果启用了 signal
选项,则在对应的 AbortController
上调用 .abort()
类似于在服务器上调用 .close()
:
const controller = new AbortController();
server.listen({
host: 'localhost',
port: 80,
signal: controller.signal
});
// 稍后,当要关闭服务器时。
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>
启动 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
的服务器上调用 ref()
不会让程序退出。
如果服务器被 ref
,则再次调用 ref()
将无效。
server.unref()
#
- 返回: <net.Server>
如果服务器是事件系统中唯一的活动服务器,则在服务器上调用 unref()
将允许程序退出。
如果服务器已经被 unref
,则再次调用 unref()
将无效。
net.Socket
类#
- 继承自: <stream.Duplex>
此类是 TCP 套接字或流式 IPC 端点(在 Windows 上使用命名管道,否则使用 Unix 域套接字)的抽象。
它也是 EventEmitter
。
net.Socket
可以由用户创建并直接用于与服务器交互。
例如,通过 net.createConnection()
返回它,因此用户可以使用它与服务器对话。
它也可以由 Node.js 创建并在接收到连接时传给用户。
例如,它被传给在 net.Server
上触发的 'connection'
事件的监听器,因此用户可以使用它与客户端进行交互。
new net.Socket([options])
#
options
<Object> 可用的选项有: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
<Error> | <null> 错误对象。 参见dns.lookup()
。address
<string> IP 地址。family
<string> | <null> 地址类型。 参见dns.lookup()
。host
<string> 主机名。
'ready'
事件#
当套接字准备好使用时触发。
'connect'
后立即触发。
'timeout'
事件#
如果套接字因不活动而超时则触发。 这只是通知套接字已空闲。 用户必须手动关闭连接。
另见: socket.setTimeout()
。
socket.address()
#
- 返回: <Object>
返回操作系统报告的绑定 address
、地址 family
名称和套接字的 port
:{ port: 12346, family: 'IPv4', address: '127.0.0.1' }
socket.bufferSize
#
writable.writableLength
。此属性显示为写入而缓冲的字符数。 缓冲区可能包含编码后长度未知的字符串。 所以这个数字只是缓冲区中字节数的近似值。
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'
事件并将错误传给 'error'
监听器,而不是触发 'connect'
事件。
最后一个参数 connectListener
(如果提供)将作为 'connect'
事件的监听器添加一次。
此函数仅用于在触发 'close'
之后重新连接套接字,否则可能导致未定义的行为。
socket.connect(options[, connectListener])
#
options
<Object>connectListener
<Function>socket.connect()
方法的常用参数。 将被添加为'connect'
事件的监听器一次。- 返回: <net.Socket> 套接字自身
在给定的套接字上发起连接。
一般不需要这个方法,套接字应该用 net.createConnection()
创建和打开。
仅在实现自定义套接字时使用它。
对于 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
。
对于 IPC 连接,可用的 options
是:
path
<string> 必需的。 客户端应该连接到的路径。 请参阅标识 IPC 连接的路径。 如果提供,则忽略上面特定于 TCP 的选项。
对于这两种类型,可用的 options
包括:
onread
<Object> 如果指定,传入的数据存储在单个buffer
中,并在数据到达套接字时传给提供的callback
。 这将导致流功能不提供任何数据。 套接字将像往常一样触发'error'
、'end'
和'close'
等事件。pause()
和resume()
等方法也将按预期运行。buffer
<Buffer> | <Uint8Array> | <Function> 用于存储传入数据的可重用内存块或返回此类数据的函数。callback
<Function> 为每个传入数据块调用此函数。 传给它的有两个参数:写入buffer
的字节数和对buffer
的引用。 从此函数返回false
以隐式pause()
套接字。 该函数将在全局上下文中执行。
以下是使用 onread
选项的客户端示例:
const net = require('node: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
<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
<Object>- 返回: <net.Socket>
确保此套接字上不再发生 I/O 活动。 销毁流并关闭连接。
有关详细信息,请参阅 writable.destroy()
。
socket.destroyed
#
- <boolean> 指示连接是否被破坏。 一旦连接被破坏,就不能再使用它传输数据。
有关详细信息,请参阅 writable.destroyed
。
socket.end([data[, encoding]][, callback])
#
data
<string> | <Buffer> | <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
套接字上调用 ref()
不会让程序退出。
如果套接字是 ref
的,再次调用 ref
将无效。
socket.remoteAddress
#
远程 IP 地址的字符串表示形式。
例如,'74.125.127.100'
或 '2001:4860:a005::68'
。
如果套接字被破坏(例如,如果客户端断开连接),则值可能是 undefined
。
socket.remoteFamily
#
远程 IP 系列的字符串表示形式。
'IPv4'
或 'IPv6'
。
socket.remotePort
#
远程端口的数字表示。
例如,80
或 21
。
socket.resetAndDestroy()
#
- 返回: <net.Socket>
通过发送 RST 数据包关闭 TCP 连接并销毁流。
如果此 TCP 套接字处于连接状态,则它会发送一个 RST 数据包,一旦连接就销毁此 TCP 套接字。
否则,它将使用 ERR_SOCKET_CLOSED
错误调用 socket.destroy
。
如果此不是 TCP 套接字(例如管道),则调用此方法将立即抛出 ERR_INVALID_HANDLE_TYPE
错误。
socket.resume()
#
- 返回: <net.Socket> 套接字自身
调用 socket.pause()
后继续读取。
socket.setEncoding([encoding])
#
encoding
<string>- 返回: <net.Socket> 套接字自身
将套接字的编码设置为可读流。
有关详细信息,请参阅 readable.setEncoding()
。
socket.setKeepAlive([enable][, initialDelay])
#
enable
<boolean> 默认值:false
initialDelay
<number> 默认值:0
- 返回: <net.Socket> 套接字自身
启用/禁用保持活动功能,并可选择在空闲套接字上发送第一个保持活动探测之前设置初始延迟。
设置 initialDelay
(以毫秒为单位)以设置接收到的最后一个数据包和第一个保持活动探测之间的延迟。
将 0
设置为 initialDelay
将使该值与默认(或先前)设置保持不变。
启用保持活动功能将设置以下套接字选项:
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
#
由 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()
方法。
socket.readyState
#
此属性将连接状态表示为字符串。
- 如果流正在连接,则
socket.readyState
是opening
。 - 如果流可读可写,则为
open
。 - 如果流可读不可写,则为
readOnly
。 - 如果流不可读写,则为
writeOnly
。
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.createConnection(options[, connectListener])
的别名。
net.connect(path[, connectListener])
#
path
<string>connectListener
<Function>- 返回: <net.Socket>
net.createConnection(path[, connectListener])
的别名。
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()
部分中描述的回显服务器的客户端示例:
const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
// 'connect' 监听器。
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' });
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
。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()
什么。
这是一个 TCP 回显服务器的示例,它监听端口 8124 上的连接:
const net = require('node:net');
const server = net.createServer((c) => {
// 'connection' 监听器。
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.isIP(input)
#
如果 input
是 IPv6 地址,则返回 6
。
如果 input
是点十进制表示法中没有前导零的 IPv4 地址,则返回 4
。
否则,返回 0
。
net.isIP('::1'); // 返回 6
net.isIP('127.0.0.1'); // 返回 4
net.isIP('127.000.000.001'); // 返回 0
net.isIP('127.0.0.1/24'); // 返回 0
net.isIP('fhqwhgads'); // 返回 0
net.isIPv4(input)
#
如果 input
是点十进制表示法中没有前导零的 IPv4 地址,则返回 true
。
否则,返回 false
。
net.isIPv4('127.0.0.1'); // 返回 true
net.isIPv4('127.000.000.001'); // 返回 false
net.isIPv4('127.0.0.1/24'); // 返回 false
net.isIPv4('fhqwhgads'); // 返回 false
net.isIPv6(input)
#
如果 input
是 IPv6 地址,则返回 true
。
否则,返回 false
。
net.isIPv6('::1'); // 返回 true
net.isIPv6('fhqwhgads'); // 返回 false