Node.js v18.7.0 文档

dns.Resolver 类#

中英对照

域名系统请求的独立解析器。

Resolver([options])#

中英对照

创建新的解析器。

resolver.cancel()#

中英对照

取消此解析器进行的所有未完成的域名系统查询。 相应的回调将被调用，错误码为 ECANCELLED。

resolver.setLocalAddress([ipv4][, ipv6])#

中英对照

解析器实例将从指定的 IP 地址发送其请求。 这允许程序在多宿主系统上使用时指定出站接口。

dns.getServers()#

中英对照

返回 IP 地址字符串的数组，根据 RFC 5952 格式化，当前配置为用于 DNS 解析。 如果使用自定义端口，则字符串将包含端口部分。

dns.lookup(hostname[, options], callback)#

中英对照

将主机名（例如 'nodejs.org'）解析为第一个找到的 A (IPv4) 或 AAAA (IPv6) 记录。 所有 option 属性都是可选的。 如果 options 是整数，则它必须是 4 或 6，如果 options 是 0 或未提供，则返回 IPv4 和 IPv6 地址（如果找到）。

支持的 getaddrinfo#

中英对照

以下标志可以作为提示传给 dns.lookup()。

dns.lookupService(address, port, callback)#

中英对照

使用操作系统的底层 getnameinfo 实现将给定的 address 和 port 解析为主机名和服务。

dns.resolve(hostname[, rrtype], callback)#

中英对照

使用域名系统协议将主机名（例如 'nodejs.org'）解析为资源记录数组。 callback 函数有参数 (err, records)。 当成功时，records 将是资源记录数组。 个别结果的类型和结构因 rrtype 而异：

dns.resolve4(hostname[, options], callback)#

中英对照

使用域名系统协议为 hostname 解析 IPv4 地址（A 记录）。 传给 callback 函数的 addresses 参数将包含 IPv4 地址的数组（例如 ['74.125.79.104', '74.125.79.105', '74.125.79.106']）。

dns.resolve6(hostname[, options], callback)#

中英对照

使用域名系统协议为 hostname 解析 IPv6 地址（AAAA 记录）。 传给 callback 函数的 addresses 参数将包含 IPv6 地址数组。

dns.resolveAny(hostname, callback)#

中英对照

使用域名系统协议解析所有记录（也称为 ANY 或 * 查询）。 传给 callback 函数的 ret 参数将是包含各种类型记录的数组。 每个对象都有表示当前记录的类型的属性 type。 并且根据 type，对象上将出现其他属性：

dns.resolveCname(hostname, callback)#

中英对照

使用域名系统协议为 hostname 解析 CNAME 记录。 传给 callback 函数的 addresses 参数将包含可用于 hostname（例如 ['bar.example.com']）的规范名称记录的数组。

dns.resolveCaa(hostname, callback)#

中英对照

使用域名系统协议为 hostname 解析 CAA 记录。 传给 callback 函数的 addresses 参数将包含可用于 hostname（例如 [{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]）的证书颁发机构授权记录的数组。

dns.resolveMx(hostname, callback)#

中英对照

使用域名系统协议解析 hostname 的邮件交换记录（MX 记录）。 传给 callback 函数的 addresses 参数将包含其中包含 priority 和 exchange 属性（例如 [{priority: 10, exchange: 'mx.example.com'}, ...]）的对象数组。

dns.resolveNaptr(hostname, callback)#

中英对照

使用域名系统协议为 hostname 解析基于正则表达式的记录（NAPTR 记录）。 传给 callback 函数的 addresses 参数将包含具有以下属性的对象数组：

dns.resolveNs(hostname, callback)#

中英对照

使用域名系统协议为 hostname 解析名称服务器记录（NS 记录）。 传给 callback 函数的 addresses 参数将包含可用于 hostname（例如 ['ns1.example.com', 'ns2.example.com']）的名称服务器记录数组。

dns.resolvePtr(hostname, callback)#

中英对照

使用域名系统协议解析 hostname 的指针记录（PTR 记录）。 传给 callback 函数的 addresses 参数将是包含回复记录的字符串数组。

dns.resolveSoa(hostname, callback)#

中英对照

使用域名系统协议来解析 hostname 的起始规范记录（SOA 记录）。 传给 callback 函数的 address 参数将是具有以下属性的对象：

dns.resolveSrv(hostname, callback)#

中英对照

使用域名系统协议解析 hostname 的服务记录（SRV 记录）。 传给 callback 函数的 addresses 参数将是具有以下属性的对象数组：

dns.resolveTxt(hostname, callback)#

中英对照

使用域名系统协议为 hostname 解析文本查询（TXT 记录）。 传给 callback 函数的 records 参数是可用于 hostname（例如 [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]）的文本记录的二维数组。 每个子数组包含一条记录的 TXT 块。 根据用例，这些可以连接在一起或单独处理。

dns.reverse(ip, callback)#

中英对照

执行反向域名系统查询，将 IPv4 或 IPv6 地址解析为主机名数组。

dns.setDefaultResultOrder(order)#

中英对照

在 dns.lookup() 和 dnsPromises.lookup() 中设置 verbatim 的默认值。 该值可能是：

dns.setServers(servers)#

中英对照

设置执行 DNS 解析时要使用的服务器的 IP 地址和端口。 servers 参数是 RFC 5952 格式的地址数组。 如果端口是 IANA 默认 DNS 端口 (53)，则可以省略。

Promise 形式的 API#

中英对照

dns.promises API 提供了一组替代的异步 DNS 方法，这些方法返回 Promise 对象而不是使用回调。 API 可通过 require('node:dns').promises 或 require('node:dns/promises') 访问。

dnsPromises.Resolver 类#

中英对照

域名系统请求的独立解析器。

resolver.cancel()#

中英对照

取消此解析器进行的所有未完成的域名系统查询。 相应的 promise 将使用错误码 ECANCELLED 拒绝。

dnsPromises.getServers()#

中英对照

返回 IP 地址字符串的数组，根据 RFC 5952 格式化，当前配置为用于 DNS 解析。 如果使用自定义端口，则字符串将包含端口部分。

dnsPromises.lookup(hostname[, options])#

中英对照

将主机名（例如 'nodejs.org'）解析为第一个找到的 A (IPv4) 或 AAAA (IPv6) 记录。 所有 option 属性都是可选的。 如果 options 是整数，则它必须是 4 或 6 – 如果未提供 options，则如果找到，则返回 IPv4 和 IPv6 地址。

dnsPromises.lookupService(address, port)#

中英对照

使用操作系统的底层 getnameinfo 实现将给定的 address 和 port 解析为主机名和服务。

dnsPromises.resolve(hostname[, rrtype])#

中英对照

使用域名系统协议将主机名（例如 'nodejs.org'）解析为资源记录数组。 当成功时，Promise 使用资源记录数组解决。 个别结果的类型和结构因 rrtype 而异：

dnsPromises.resolve4(hostname[, options])#

中英对照

使用域名系统协议为 hostname 解析 IPv4 地址（A 记录）。 当成功时，Promise 使用 IPv4 地址数值（例如 ['74.125.79.104', '74.125.79.105', '74.125.79.106']）解决。

dnsPromises.resolve6(hostname[, options])#

中英对照

使用域名系统协议为 hostname 解析 IPv6 地址（AAAA 记录）。 当成功时，Promise 使用 IPv6 地址数组解决。

dnsPromises.resolveAny(hostname)#

中英对照

使用域名系统协议解析所有记录（也称为 ANY 或 * 查询）。 当成功时，Promise 使用包含各种类型记录的数组进行解决。 每个对象都有表示当前记录的类型的属性 type。 并且根据 type，对象上将出现其他属性：

dnsPromises.resolveCaa(hostname)#

中英对照

使用域名系统协议为 hostname 解析 CAA 记录。 当成功时，Promise 使用包含可用于 hostname（例如 [{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]）的可用证书颁发机构授权记录的对象数组进行解决。

dnsPromises.resolveCname(hostname)#

中英对照

使用域名系统协议为 hostname 解析 CNAME 记录。 当成功时，Promise 使用 hostname 可用的规范名称记录数组（例如 ['bar.example.com']）进行解决。

dnsPromises.resolveMx(hostname)#

中英对照

使用域名系统协议解析 hostname 的邮件交换记录（MX 记录）。 当成功时，Promise 使用包含 priority 和 exchange 属性（例如 [{priority: 10, exchange: 'mx.example.com'}, ...]）的对象数组进行解决。

dnsPromises.resolveNaptr(hostname)#

中英对照

使用域名系统协议为 hostname 解析基于正则表达式的记录（NAPTR 记录）。 当成功时，Promise 使用具有以下属性的对象数组进行解决：

dnsPromises.resolveNs(hostname)#

中英对照

使用域名系统协议为 hostname 解析名称服务器记录（NS 记录）。 当成功时，Promise 使用可用于 hostname 的名称服务器记录数组（例如 ['ns1.example.com', 'ns2.example.com']）进行解决。

dnsPromises.resolvePtr(hostname)#

中英对照

使用域名系统协议解析 hostname 的指针记录（PTR 记录）。 当成功时，Promise 使用包含回复记录的字符串数组进行解决。

dnsPromises.resolveSoa(hostname)#

中英对照

使用域名系统协议来解析 hostname 的起始规范记录（SOA 记录）。 当成功时，Promise 使用具有以下属性的对象进行解决：

dnsPromises.resolveSrv(hostname)#

中英对照

使用域名系统协议解析 hostname 的服务记录（SRV 记录）。 当成功时，Promise 使用具有以下属性的对象数组进行解决：

dnsPromises.resolveTxt(hostname)#

中英对照

使用域名系统协议为 hostname 解析文本查询（TXT 记录）。 当成功时，Promise 使用可用于 hostname（例如 [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]）的文本记录的二维数组进行解决。 每个子数组包含一条记录的 TXT 块。 根据用例，这些可以连接在一起或单独处理。

dnsPromises.reverse(ip)#

中英对照

执行反向域名系统查询，将 IPv4 或 IPv6 地址解析为主机名数组。

dnsPromises.setDefaultResultOrder(order)#

中英对照

在 dns.lookup() 和 dnsPromises.lookup() 中设置 verbatim 的默认值。 该值可能是：

dnsPromises.setServers(servers)#

中英对照

设置执行 DNS 解析时要使用的服务器的 IP 地址和端口。 servers 参数是 RFC 5952 格式的地址数组。 如果端口是 IANA 默认 DNS 端口 (53)，则可以省略。

错误码#

中英对照

每个域名系统查询都可以返回以下错误代码之一：

实现的注意事项#

中英对照

尽管 dns.lookup() 和各种 dns.resolve*()/dns.reverse() 函数具有将网络名称与网络地址相关联的相同目标（反之亦然），但它们的行为却大不相同。 这些差异可能会对 Node.js 程序的行为产生微妙但重要的影响。

dns.lookup()#

中英对照

在幕后，dns.lookup() 使用与大多数其他程序相同的操作系统设施。 例如，dns.lookup() 几乎总是以与 ping 命令相同的方式解析给定名称。 在大多数类似 POSIX 的操作系统上，可以通过更改 nsswitch.conf(5) 和/或 resolv.conf(5) 中的设置来修改 dns.lookup() 函数的行为，但更改这些文件将更改在同一操作系统上运行的所有其他程序的行为。

dns.resolve()、dns.resolve*() 与 dns.reverse()#

中英对照

这些函数的实现与 dns.lookup() 完全不同。 它们不使用 getaddrinfo(3)，其总是在网络上执行域名系统查询。 此网络通信始终异步完成，不使用 libuv 的线程池。