Node.js v18.18.2 文档

类：dns.Resolver#

DNS 请求的独立解析器。

创建新的解析器使用默认服务器设置。使用resolver.setServers()设置用于解析器的服务器 不会影响其他解析器：

const { Resolver } = require('node:dns');
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// This request will use the server at 4.4.4.4, independent of global settings.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
}); copy

node:dns模块中的以下方法可用：

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

Resolver([options])#

创建一个新的解析器。

• options <对象>
  • timeout <integer>查询超时（以毫秒为单位），或-1使用默认超时。
  • tries <整数>解析器在放弃之前尝试联系每个名称服务器的尝试次数。默认值： 4

resolver.cancel()#

取消此解析器发出的所有未完成的 DNS 查询。相应的回调将被调用，并出现错误，代码为ECANCELLED。

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

• ipv4 <string> IPv4 地址的字符串表示形式。 默认值： '0.0.0.0'
• ipv6 <string> IPv6 地址的字符串表示形式。 默认值： '::0'

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

如果未指定 v4 或 v6 地址，则将其设置为默认地址，操作系统将自动选择本地地址。

解析器在向 IPv4 DNS 服务器发出请求时将使用 v4 本地地址，在向 IPv6 DNS 服务器发出请求时将使用 v6 本地地址。解析请求的rrtype对所使用的本地地址没有影响。

dns.getServers()#

• 返回：<字符串[]>

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

[
  '4.4.4.4',
  '2001:4860:4860::8888',
  '4.4.4.4:1053',
  '[2001:4860:4860::8888]:1053',
] copy

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

• hostname <字符串>
• options <整数> | <对象>
  • family <整数> | <string>记录系列。必须是4、6或0。出于向后兼容性的原因，'IPv4'和'IPv6'分别解释为4 和6 。值0表示同时返回 IPv4 和 IPv6 地址。默认值： 0。
  • hints <number>一个或多个受支持的getaddrinfo标志。多个标志可以通过按位OR对其值进行传递。
  • all <boolean>当true时，回调返回数组中的所有解析地址。否则，返回单个地址。默认值： false。
  • verbatim <boolean>当true时，回调按照 DNS 解析器返回的顺序接收 IPv4 和 IPv6 地址。当false时，IPv4 地址放置在 IPv6 地址之前。 默认值： true（地址不重新排序）。默认值可使用dns.setDefaultResultOrder()或 --dns-result-order配置。
• callback <函数>
  • err <错误>
  • address <string> IPv4 或 IPv6 地址的字符串表示形式。
  • family <整数> 4或6 ，表示address的族，或0如果地址是不是 IPv4 或 IPv6 地址。0可能表明操作系统使用的名称解析服务存在错误。

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

将all选项设置为true时， callback的参数更改为 (err, addresses)，其中addresses是具有属性address和family的对象数组。

发生错误时，err是一个Error对象，其中err.code是错误代码。请记住，不仅当主机名不存在时，而且当查找因其他原因（例如没有可用的文件描述符）失败时，err.code 都会被设置为 'ENOTFOUND'。

dns.lookup()不一定与 DNS 协议有任何关系。该实现使用可以将名称与地址关联起来的操作系统工具，反之亦然。这种实现可能会对任何 Node.js 程序的行为产生微妙但重要的影响。在使用 dns.lookup()之前，请花一些时间查阅实施注意事项部分。

用法示例：

const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.com', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] copy

如果此方法作为其util.promisify() ed 版本调用，并且all 未设置为true，则它会返回PromiseObject具有address和 family属性。

支持的 getaddrinfo 标志#

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

• dns.ADDRCONFIG：将返回的地址类型限制为系统上配置的非环回地址类型。例如，仅当当前系统至少配置了一个 IPv4 地址时，才会返回 IPv4 地址。
• dns.V4MAPPED：如果指定了 IPv6 系列，但未找到 IPv6 地址，则返回 IPv4 映射的 IPv6 地址。某些操作系统（例如 FreeBSD 10.1）不支持它。
• dns.ALL：如果指定了dns.V4MAPPED，则返回解析的 IPv6 地址以及 IPv4 映射的 IPv6 地址。

dns.lookupService(address, port, callback)#

• address <字符串>
• port <数字>
• callback <函数>
  • err <错误>
  • hostname <字符串>例如example.com
  • service <字符串>例如http

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

如果address不是有效的 IP 地址，则会抛出TypeError 。port将被强制转换为数字。如果不是合法端口， 则会抛出TypeError 。

发生错误时，err是一个Error对象，其中err.code是错误代码。

const dns = require('node:dns');
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service);
  // Prints: localhost ssh
}); copy

如果此方法作为其util.promisify() ed 版本调用，它将返回一个 Promise，其中包含hostname和service特性。

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

• hostname <string>要解析的主机名。
• rrtype <string>资源记录类型。默认值： 'A'。
• callback <函数>
  • err <错误>
  • records <字符串[]> | <对象[]> | <对象>

使用 DNS 协议将主机名（例如'nodejs.org'）解析为资源记录数组。callback函数具有参数 (err, records)。成功后，records将是一个资源记录数组。各个结果的类型和结构根据rrtype有所不同：

出错时，err是一个Error对象，其中err.code是DNS 错误代码之一 。

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

• hostname <string>要解析的主机名。
• options <对象>
  • ttl <boolean>检索每条记录的生存时间值 (TTL)。当true时，回调接收{ address: '1.2.3.4', ttl: 60 }对象数组 而不是字符串数组，TTL 以秒为单位。
• callback <函数>
  • err <错误>
  • addresses <字符串[]> | <对象[]>

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

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

• hostname <string>要解析的主机名。
• options <对象>
  • ttl <boolean>检索每条记录的生存时间值 (TTL)。当true时，回调接收{ address: '0:1:2:3:4:5:6:7', ttl: 60 }对象数组 而不是字符串数组，TTL 以秒为单位。
• callback <函数>
  • err <错误>
  • addresses <字符串[]> | <对象[]>

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

dns.resolveAny(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • ret <对象[]>

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

以下是传递给回调的ret对象的示例：

[ { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  { type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60 } ] copy

DNS 服务器运营商可以选择不响应ANY 查询。最好调用单独的方法，例如dns.resolve4()、 dns.resolveMx()等。有关更多详细信息，请参阅RFC 8482。

dns.resolveCname(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • addresses <字符串[]>

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

dns.resolveCaa(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • records <对象[]>

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

dns.resolveMx(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • addresses <对象[]>

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

dns.resolveNaptr(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • addresses <对象[]>

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

• flags
• service
• regexp
• replacement
• order
• preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
} copy

dns.resolveNs(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • addresses <字符串[]>

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

dns.resolvePtr(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • addresses <字符串[]>

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

dns.resolveSoa(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • address <对象>

使用 DNS 协议解析 hostname 的授权记录起始点（ SOA记录）。传递给callback函数的address参数将是具有以下属性的对象：

• nsname
• hostmaster
• serial
• refresh
• retry
• expire
• minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

dns.resolveSrv(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • addresses <对象[]>

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

• priority
• weight
• port
• name

{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
} copy

dns.resolveTxt(hostname, callback)#

• hostname <字符串>
• callback <函数>
  • err <错误>
  • records <字符串[][]>

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

dns.reverse(ip, callback)#

• ip <字符串>
• callback <函数>
  • err <错误>
  • hostnames <字符串[]>

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

出错时，err是一个Error对象，其中err.code是DNS 错误代码之一。

dns.setDefaultResultOrder(order)#

• order <string>必须是'ipv4first'或'verbatim'。

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

• ipv4first：设置默认值verbatim false。
• verbatim：设置默认值verbatim true。

默认值为verbatim且dns.setDefaultResultOrder() 的优先级高于--dns-result-order。使用工作线程时， 主线程中的dns.setDefaultResultOrder()不会影响工作线程中的默认 dns 顺序。

dns.getDefaultResultOrder()#

获取dns.lookup()和 dnsPromises.lookup()中verbatim的默认值。该值可以是：

• ipv4first：对于verbatim默认为false。
• verbatim：对于verbatim默认为true。

dns.setServers(servers)#

• servers <string[]> RFC 5952格式地址数组

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

dns.setServers([
  '4.4.4.4',
  '[2001:4860:4860::8888]',
  '4.4.4.4:1053',
  '[2001:4860:4860::8888]:1053',
]); copy

如果提供无效地址，将会抛出错误。

当 DNS 查询正在进行时，不得调用dns.setServers()方法。

dns.setServers()方法仅影响dns.resolve()、 dns.resolve*()和dns.reverse()（特别不影响 dns.lookup()）。

此方法的工作原理与 resolve.conf非常相似。也就是说，如果尝试使用提供的第一个服务器进行解析会导致 NOTFOUND错误，则resolve()方法将不会尝试使用提供的后续服务器进行解析。仅当较早的 DNS 服务器超时或导致其他错误时，才会使用后备 DNS 服务器。

DNS Promise API#

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

类：dnsPromises.Resolver#

DNS 请求的独立解析器。

创建新的解析器使用默认服务器设置。使用resolver.setServers()设置用于解析器的服务器 不会影响其他解析器：

const { Resolver } = require('node:dns').promises;
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// This request will use the server at 4.4.4.4, independent of global settings.
resolver.resolve4('example.org').then((addresses) => {
  // ...
});

// Alternatively, the same code can be written using async-await style.
(async function() {
  const addresses = await resolver.resolve4('example.org');
})(); copy

dnsPromises API 中提供了以下方法：

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

resolver.cancel()#

取消此解析器发出的所有未完成的 DNS 查询。相应的 Promise 将被拒绝，并出现代码为ECANCELLED的错误。

dnsPromises.getServers()#

• 返回：<字符串[]>

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

[
  '4.4.4.4',
  '2001:4860:4860::8888',
  '4.4.4.4:1053',
  '[2001:4860:4860::8888]:1053',
] copy

dnsPromises.lookup(hostname[, options])#

• hostname <字符串>
• options <整数> | <对象>
  • family <整数>记录系列。必须是4、6或0。值 0表示同时返回 IPv4 和 IPv6 地址。默认值： 0。
  • hints <number>一个或多个受支持的getaddrinfo标志。多个标志可以通过按位OR对其值进行传递。
  • all <boolean>当true时，将使用数组中的所有地址解析Promise 。否则，返回单个地址。默认值： false。
  • verbatim <boolean>当true时，将按照 DNS 解析器返回的顺序使用 IPv4 和 IPv6 地址解析 Promise 。当false时，IPv4 地址放置在 IPv6 地址之前。 默认值：当前为false（地址已重新排序），但预计在不久的将来会发生变化。默认值可使用dns.setDefaultResultOrder()或 --dns-result-order配置。新代码应使用{ verbatim: true }。

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

将all选项设置为true时，Promise被解析为addresses是具有属性address} 的对象数组和family。

出错时，Promise会被拒绝，并返回一个Error对象，其中err.code 是错误代码。请记住，不仅当主机名不存在时，而且当查找因其他原因（例如没有可用的文件描述符）失败时，err.code 都会设置为 'ENOTFOUND'。

dnsPromises.lookup()不一定与 DNS 协议有任何关系。该实现使用可以将名称与地址关联起来的操作系统工具，反之亦然。这种实现可能会对任何 Node.js 程序的行为产生微妙但重要的影响。在使用dnsPromises.lookup()之前，请花一些时间查阅实施注意事项部分。

用法示例：

const dns = require('node:dns');
const dnsPromises = dns.promises;
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

dnsPromises.lookup('example.com', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.com', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
}); copy

dnsPromises.lookupService(address, port)#

• address <字符串>
• port <数字>

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

如果address不是有效的 IP 地址，则会抛出TypeError 。port将被强制转换为数字。如果不是合法端口， 则会抛出TypeError 。

出错时，Promise会被拒绝，并返回一个Error对象，其中err.code 是错误代码。

const dnsPromises = require('node:dns').promises;
dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
  console.log(result.hostname, result.service);
  // Prints: localhost ssh
}); copy

dnsPromises.resolve(hostname[, rrtype])#

• hostname <string>要解析的主机名。
• rrtype <string>资源记录类型。默认值： 'A'。

使用 DNS 协议将主机名（例如'nodejs.org'）解析为资源记录数组。成功后，将使用资源记录数组解析Promise 。各个结果的类型和结构根据rrtype有所不同：

出错时，Promise会被拒绝并带有Error对象，其中err.code是DNS 错误代码 之一。

dnsPromises.resolve4(hostname[, options])#

• hostname <string>要解析的主机名。
• options <对象>
  • ttl <boolean>检索每条记录的生存时间值 (TTL)。当true时，Promise使用{ address: '1.2.3.4', ttl: 60 }对象数组 而不是字符串数组进行解析，TTL 以秒为单位表示。

使用 DNS 协议解析 hostname 的 IPv4 地址（ A记录） 。成功后，将使用 IPv4 地址数组解析Promise （例如['74.125.79.104', '74.125.79.105', '74.125.79.106']）。

dnsPromises.resolve6(hostname[, options])#

• hostname <string>要解析的主机名。
• options <对象>
  • ttl <boolean>检索每条记录的生存时间值 (TTL)。当true时，Promise使用{ address: '0:1:2:3:4:5:6:7', ttl: 60 }对象数组 而不是字符串数组进行解析，TTL 以秒为单位表示。

使用 DNS 协议解析 hostname 的 IPv6 地址（AAAA记录） 。成功后，将使用 IPv6 地址数组解析Promise 。

dnsPromises.resolveAny(hostname)#

• hostname <字符串>

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

这是结果对象的示例：

[ { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  { type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60 } ] copy

dnsPromises.resolveCaa(hostname)#

• hostname <字符串>

使用 DNS 协议解析hostname的CAA记录。成功后，将使用包含可用于hostname的可用证书颁发机构授权记录的对象数组来解析 Promise （例如[{critical: 0, iodef: 'mailto:[email protected]'},{critical: 128, issue: 'pki.example.com'}]）。

dnsPromises.resolveCname(hostname)#

• hostname <字符串>

使用 DNS 协议解析hostname的CNAME记录。成功后，将使用可用于hostname的规范名称记录数组解析 Promise（例如['bar.example.com']）。

dnsPromises.resolveMx(hostname)#

• hostname <字符串>

使用 DNS 协议解析 hostname 的邮件交换记录（MX记录） 。成功后，将使用包含priority和exchange属性（例如 [{priority: 10, exchange: 'mx.example.com'}, ...]）的对象数组解析 Promise 。

dnsPromises.resolveNaptr(hostname)#

• hostname <字符串>

使用 DNS 协议解析hostname的基于正则表达式的记录（NAPTR 记录）。成功后，将使用具有以下属性的对象数组解析Promise ：

• flags
• service
• regexp
• replacement
• order
• preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
} copy

dnsPromises.resolveNs(hostname)#

• hostname <字符串>

使用 DNS 协议解析 hostname 的名称服务器记录（ NS记录） 。成功后，将使用可用于hostname的名称服务器记录数组解析Promise（例如 ['ns1.example.com', 'ns2.example.com']）。

dnsPromises.resolvePtr(hostname)#

• hostname <字符串>

使用 DNS 协议解析 hostname 的指针记录（PTR记录） 。成功后，将使用包含回复记录的字符串数组解析Promise 。

dnsPromises.resolveSoa(hostname)#

• hostname <字符串>

使用 DNS 协议解析 hostname 的授权记录起始点（ SOA记录）。成功后，将使用具有以下属性的对象解析Promise ：

• nsname
• hostmaster
• serial
• refresh
• retry
• expire
• minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

dnsPromises.resolveSrv(hostname)#

• hostname <字符串>

使用 DNS 协议解析 hostname 的服务记录（ SRV记录） 。成功后，将使用具有以下属性的对象数组解析Promise ：

• priority
• weight
• port
• name

{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
} copy

dnsPromises.resolveTxt(hostname)#

• hostname <字符串>

使用 DNS 协议解析 hostname 的文本查询（ TXT记录） 。成功后，将使用可用于hostname的文本记录的二维数组解析 Promise（例如 [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]）。每个子数组包含一条记录的 TXT 块。根据用例，它们可以结合在一起或单独处理。

dnsPromises.reverse(ip)#

• ip <字符串>

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

出错时，Promise会被Error对象拒绝，其中err.code是DNS 错误代码 之一。

dnsPromises.setDefaultResultOrder(order)#

• order <string>必须是'ipv4first'或'verbatim'。

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

• ipv4first：设置默认值verbatim false。
• verbatim：设置默认值verbatim true。

默认值为verbatim且dnsPromises.setDefaultResultOrder() 的优先级高于--dns-result-order。使用工作线程时， 主线程中的dnsPromises.setDefaultResultOrder()不会影响工作线程中的默认 dns 顺序。

dnsPromises.getDefaultResultOrder()#

获取dnsOrder的值。

dnsPromises.setServers(servers)#

• servers <string[]> RFC 5952格式地址数组

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

dnsPromises.setServers([
  '4.4.4.4',
  '[2001:4860:4860::8888]',
  '4.4.4.4:1053',
  '[2001:4860:4860::8888]:1053',
]); copy

如果提供无效地址，将会抛出错误。

当 DNS 查询正在进行时，不得调用dnsPromises.setServers()方法。

此方法的工作原理与 resolve.conf非常相似。也就是说，如果尝试使用提供的第一个服务器进行解析会导致 NOTFOUND错误，则resolve()方法将不会尝试使用提供的后续服务器进行解析。仅当较早的 DNS 服务器超时或导致其他错误时，才会使用后备 DNS 服务器。

错误代码#

每个 DNS 查询都可能返回以下错误代码之一：

• dns.NODATA：DNS 服务器返回没​​有数据的答案。
• dns.FORMERR：DNS 服务器声明查询格式错误。
• dns.SERVFAIL：DNS 服务器返回一般失败。
• dns.NOTFOUND：未找到域名。
• dns.NOTIMP：DNS 服务器未执行请求的操作。
• dns.REFUSED：DNS 服务器拒绝查询。
• dns.BADQUERY：DNS 查询格式错误。
• dns.BADNAME：主机名格式错误。
• dns.BADFAMILY：不支持的地址族。
• dns.BADRESP：DNS 回复格式错误。
• dns.CONNREFUSED：无法联系 DNS 服务器。
• dns.TIMEOUT：联系 DNS 服务器超时。
• dns.EOF：文件结束。
• dns.FILE：读取文件时出错。
• dns.NOMEM：内存不足。
• dns.DESTRUCTION：通道正在被破坏。
• dns.BADSTR：字符串格式错误。
• dns.BADFLAGS：指定了非法标志。
• dns.NONAME：给定的主机名不是数字。
• dns.BADHINTS：指定了非法提示标志。
• dns.NOTINITIALIZED：c-ares 库初始化尚未执行。
• dns.LOADIPHLPAPI：加载iphlpapi.dll时出错。
• dns.ADDRGETNETWORKPARAMS：找不到GetNetworkParams函数。
• dns.CANCELLED：DNS 查询已取消。

dnsPromises API还会导出上述错误代码，例如dnsPromises.NODATA。

实施注意事项#

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

dns.lookup()#

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

虽然从 JavaScript 的角度来看，对dns.lookup() 的调用是异步的，但它是作为对在 libuv 线程池上运行的getaddrinfo(3)的同步调用来实现的。这可能会对某些应用程序产生令人惊讶的负面性能影响，请参阅UV_THREADPOOL_SIZE 文档以了解更多信息。

各种网络 API 将在内部调用dns.lookup()来解析主机名。如果这是一个问题，请考虑使用dns.resolve()将主机名解析为地址，并使用该地址而不是主机名。此外，某些网络 API（例如socket.connect()和dgram.createSocket() ）允许替换默认解析器dns.lookup() 。

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

这些函数的实现方式与dns.lookup()完全不同。它们不使用getaddrinfo(3)，并且始终在网络上执行 DNS 查询。这种网络通信始终是异步完成的，并且不使用 libuv 的线程池。

因此，这些函数不会对 libuv 线程池上发生的其他处理产生与dns.lookup()相同的负面影响。

它们不使用与dns.lookup()使用的同一组配置文件 。例如，他们不使用/etc/hosts中的配置。