DNS#

稳定性:2 - 稳定

源代码: lib/dns.js

node:dns 模块启用了名称解析。例如,用它来查找主机的 IP 地址。

虽然它以域名系统 (DNS)命名,但它并不总是使用 DNS 协议进行查找。dns.lookup() 使用操作系统设施来执行名称解析。它可能不需要执行任何网络通信。要像同一系统上的其他应用程序一样执行名称解析,请使用 dns.lookup()

import dns from 'node:dns';

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6const dns = require('node:dns');

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

node:dns 模块中的所有其他函数都会连接到实际的 DNS 服务器来执行名称解析。它们将始终使用网络来执行 DNS 查询。这些函数不使用与 dns.lookup() 相同的配置文件集(例如 /etc/hosts)。使用这些函数可以始终执行 DNS 查询,绕过其他名称解析设施。

import dns from 'node:dns';

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err;

  console.log(`addresses: ${JSON.stringify(addresses)}`);

  addresses.forEach((a) => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err;
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
    });
  });
});const dns = require('node:dns');

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err;

  console.log(`addresses: ${JSON.stringify(addresses)}`);

  addresses.forEach((a) => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err;
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
    });
  });
});

有关更多信息,请参阅实现注意事项部分

类:dns.Resolver#

用于 DNS 请求的独立解析器。

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

import { Resolver } from '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) => {
  // ...
});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) => {
  // ...
});

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

Resolver([options])#

创建一个新的解析器。

  • options <Object>
    • timeout <integer> 查询超时(以毫秒为单位),或 -1 使用默认超时。
    • tries <integer> 解析器在放弃之前将尝试联系每个名称服务器的次数。默认值:4
    • maxTimeout <integer> 最大重试超时时间,以毫秒为单位。默认值: 0,禁用。

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 解析。如果使用了自定义端口,字符串将包含一个端口部分。

[
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
] 

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

  • hostname <string>
  • options <integer> | <Object>
    • family <integer> | <string> 记录族。必须是 460。出于向后兼容的原因,'IPv4''IPv6' 分别被解释为 46。值 0 表示返回 IPv4 或 IPv6 地址。如果值 0{ all: true }(见下文)一起使用,则会返回 IPv4 和 IPv6 地址中的一个或两个,具体取决于系统的 DNS 解析器。默认值: 0
    • hints <number> 一个或多个支持的 getaddrinfo 标志。可以通过按位运算它们的值来传递多个标志。
    • all <boolean> 当为 true 时,回调函数返回一个包含所有已解析地址的数组。否则,返回单个地址。默认值: false
    • order <string> 当为 verbatim 时,返回的已解析地址是未排序的。当为 ipv4first 时,已解析地址按 IPv4 地址在前、IPv6 地址在后的顺序排序。当为 ipv6first 时,已解析地址按 IPv6 地址在前、IPv4 地址在后的顺序排序。默认值: verbatim(地址不重新排序)。默认值可通过 dns.setDefaultResultOrder()--dns-result-order 进行配置。
    • verbatim <boolean> 当为 true 时,回调函数接收到的 IPv4 和 IPv6 地址的顺序与 DNS 解析器返回的顺序相同。当为 false 时,IPv4 地址会排在 IPv6 地址之前。此选项将被 order 弃用。当两者都指定时,order 具有更高的优先级。新代码应仅使用 order默认值: true(地址不重新排序)。默认值可通过 dns.setDefaultResultOrder()--dns-result-order 进行配置。
  • callback <Function>
    • err <Error>
    • address <string> IPv4 或 IPv6 地址的字符串表示形式。
    • family <integer> 46,表示 address 的族,如果地址不是 IPv4 或 IPv6 地址,则为 00 很可能表示操作系统使用的名称解析服务中存在错误。

将主机名(例如 'nodejs.org')解析为找到的第一个 A (IPv4) 或 AAAA (IPv6) 记录。所有 option 属性都是可选的。如果 options 是一个整数,那么它必须是 46——如果未提供 options,则如果找到,将返回 IPv4 或 IPv6 地址,或两者都返回。

all 选项设置为 true 时,callback 的参数变为 (err, addresses),其中 addresses 是一个对象数组,每个对象都有 addressfamily 属性。

出错时,err 是一个 Error 对象,其中 err.code 是错误代码。请记住,err.code 将被设置为 'ENOTFOUND',不仅在主机名不存在时,也在查找因其他原因(如没有可用的文件描述符)失败时。

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

用法示例:

import dns from 'node:dns';
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.org', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.org', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.org', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.org', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]

如果此方法以其 util.promisify() 化的版本被调用,并且 all 未设置为 true,它将返回一个 Promise,该 Promise 解析为一个具有 addressfamily 属性的 Object

支持的 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)#

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

如果 address 不是一个有效的 IP 地址,将抛出 TypeErrorport 将被强制转换为一个数字。如果它不是一个合法的端口,将抛出 TypeError

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

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

如果此方法以其 util.promisify() 化的版本被调用,它将返回一个 Promise,该 Promise 解析为一个具有 hostnameservice 属性的 Object

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

使用 DNS 协议将主机名(例如 'nodejs.org')解析为资源记录数组。callback 函数的参数为 (err, records)。成功时,records 将是一个资源记录数组。单个结果的类型和结构根据 rrtype 而变化。

rrtyperecords 包含结果类型快捷方法
'A'IPv4 地址(默认)<string>dns.resolve4()
'AAAA'IPv6 地址<string>dns.resolve6()
'ANY'任何记录<Object>dns.resolveAny()
'CAA'CA 授权记录<Object>dns.resolveCaa()
'CNAME'规范名称记录<string>dns.resolveCname()
'MX'邮件交换记录<Object>dns.resolveMx()
'NAPTR'名称权威指针记录<Object>dns.resolveNaptr()
'NS'名称服务器记录<string>dns.resolveNs()
'PTR'指针记录<string>dns.resolvePtr()
'SOA'起始授权机构记录<Object>dns.resolveSoa()
'SRV'服务记录<Object>dns.resolveSrv()
'TLSA'证书关联<Object>dns.resolveTlsa()
'TXT'文本记录<string[]>dns.resolveTxt()

出错时,err 是一个 Error 对象,其中 err.codeDNS 错误代码之一。

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

  • hostname <string> 要解析的主机名。
  • options <Object>
    • ttl <boolean> 检索每条记录的生存时间(TTL)值。当为 true 时,回调函数接收一个 { address: '1.2.3.4', ttl: 60 } 对象数组,而不是字符串数组,其中 TTL 以秒为单位表示。
  • callback <Function>

使用 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 <Object>
    • ttl <boolean> 检索每条记录的生存时间(TTL)值。当为 true 时,回调函数接收一个 { address: '0:1:2:3:4:5:6:7', ttl: 60 } 对象数组,而不是字符串数组,其中 TTL 以秒为单位表示。
  • callback <Function>

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

dns.resolveAny(hostname, callback)#

使用 DNS 协议解析所有记录(也称为 ANY* 查询)。传递给 callback 函数的 ret 参数将是一个包含各种类型记录的数组。每个对象都有一个 type 属性,指示当前记录的类型。并且根据 type,对象上还会存在其他属性。

类型属性
'A'address/ttl
'AAAA'address/ttl
'CNAME'value
'MX'请参阅 dns.resolveMx()
'NAPTR'请参阅 dns.resolveNaptr()
'NS'value
'PTR'value
'SOA'请参阅 dns.resolveSoa()
'SRV'请参阅 dns.resolveSrv()
'TLSA'请参阅 dns.resolveTlsa()
'TXT'这种类型的记录包含一个名为 entries 的数组属性,它引用了 dns.resolveTxt(),例如 { entries: ['...'], type: 'TXT' }

以下是传递给回调的 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 } ] 

DNS 服务器操作员可能选择不响应 ANY 查询。最好调用诸如 dns.resolve4()dns.resolveMx() 等单个方法。有关更多详细信息,请参阅 RFC 8482

dns.resolveCname(hostname, callback)#

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

dns.resolveCaa(hostname, callback)#

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

dns.resolveMx(hostname, callback)#

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

dns.resolveNaptr(hostname, callback)#

使用 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
} 

dns.resolveNs(hostname, callback)#

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

dns.resolvePtr(hostname, callback)#

使用 DNS 协议解析 hostname 的指针记录(PTR 记录)。传递给 callback 函数的 addresses 参数将是一个包含应答记录的字符串数组。

dns.resolveSoa(hostname, callback)#

使用 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
} 

dns.resolveSrv(hostname, callback)#

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

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

dns.resolveTlsa(hostname, callback)#

使用 DNS 协议解析 hostname 的证书关联记录(TLSA 记录)。传递给 callback 函数的 records 参数是一个具有以下属性的对象数组:

  • certUsage
  • selector
  • match
  • data
{
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer]
} 

dns.resolveTxt(hostname, callback)#

使用 DNS 协议解析 hostname 的文本查询(TXT 记录)。传递给 callback 函数的 records 参数是一个二维数组,其中包含 hostname 可用的文本记录(例如 [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ])。每个子数组包含一条记录的 TXT 块。根据用例,这些块可以连接在一起或分开处理。

dns.reverse(ip, callback)#

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

出错时,err 是一个 Error 对象,其中 err.codeDNS 错误代码之一。

dns.setDefaultResultOrder(order)#

  • order <string> 必须是 'ipv4first''ipv6first''verbatim'

设置 dns.lookup()dnsPromises.lookup()order 的默认值。该值可以是:

  • ipv4first:将默认 order 设置为 ipv4first
  • ipv6first:将默认 order 设置为 ipv6first
  • verbatim:将默认 order 设置为 verbatim

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

dns.getDefaultResultOrder()#

获取 dns.lookup()dnsPromises.lookup()order 的默认值。该值可以是:

  • ipv4first:对于默认 orderipv4first
  • ipv6first:对于默认 orderipv6first
  • verbatim:对于默认 orderverbatim

dns.setServers(servers)#

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

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

如果提供了无效地址,将抛出错误。

在 DNS 查询进行中时,不得调用 dns.setServers() 方法。

dns.setServers() 方法仅影响 dns.resolve()dns.resolve*()dns.reverse()(并且特别地影响 dns.lookup())。

此方法的工作方式很像 resolve.conf。也就是说,如果尝试使用提供的第一个服务器解析导致 NOTFOUND 错误,resolve() 方法将不会尝试使用后续提供的服务器进行解析。只有当较早的服务器超时或导致其他错误时,才会使用备用 DNS 服务器。

DNS promises API#

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

类:dnsPromises.Resolver#

用于 DNS 请求的独立解析器。

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

import { Resolver } from '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.
const addresses = await resolver.resolve4('example.org');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');
})();

dnsPromises API 中的以下方法可用

resolver.cancel()#

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

dnsPromises.getServers()#

返回一个 IP 地址字符串数组,根据 RFC 5952 格式化,这些地址当前已配置用于 DNS 解析。如果使用了自定义端口,字符串将包含一个端口部分。

[
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
] 

dnsPromises.lookup(hostname[, options])#

  • hostname <string>
  • options <integer> | <Object>
    • family <integer> 记录族。必须是 460。值 0 表示返回 IPv4 或 IPv6 地址。如果值 0{ all: true }(见下文)一起使用,则会返回 IPv4 和 IPv6 地址中的一个或两个,具体取决于系统的 DNS 解析器。默认值: 0
    • hints <number> 一个或多个支持的 getaddrinfo 标志。可以通过按位运算它们的值来传递多个标志。
    • all <boolean> 当为 true 时,Promise 解析为一个包含所有地址的数组。否则,返回单个地址。默认值: false
    • order <string> 当为 verbatim 时,Promise 解析的结果中,IPv4 和 IPv6 地址的顺序与 DNS 解析器返回的顺序相同。当为 ipv4first 时,IPv4 地址会排在 IPv6 地址之前。当为 ipv6first 时,IPv6 地址会排在 IPv4 地址之前。默认值: verbatim(地址不重新排序)。默认值可通过 dns.setDefaultResultOrder()--dns-result-order 进行配置。新代码应使用 { order: 'verbatim' }
    • verbatim <boolean> 当为 true 时,Promise 解析的结果中,IPv4 和 IPv6 地址的顺序与 DNS 解析器返回的顺序相同。当为 false 时,IPv4 地址会排在 IPv6 地址之前。此选项将被 order 弃用。当两者都指定时,order 具有更高的优先级。新代码应仅使用 order默认值: 当前为 false(地址被重新排序),但这在不久的将来预计会改变。默认值可通过 dns.setDefaultResultOrder()--dns-result-order 进行配置。

将主机名(例如 'nodejs.org')解析为找到的第一个 A (IPv4) 或 AAAA (IPv6) 记录。所有 option 属性都是可选的。如果 options 是一个整数,那么它必须是 46——如果未提供 options,则如果找到,将返回 IPv4 或 IPv6 地址,或两者都返回。

all 选项设置为 true 时,Promise 解析的结果中,addresses 是一个对象数组,每个对象都有 addressfamily 属性。

出错时,Promise 会被一个 Error 对象拒绝,其中 err.code 是错误代码。请记住,err.code 将被设置为 'ENOTFOUND',不仅在主机名不存在时,也在查找因其他原因(如没有可用的文件描述符)失败时。

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

用法示例:

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

await dnsPromises.lookup('example.org', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
await dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});const dns = require('node:dns');
const dnsPromises = dns.promises;
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

dnsPromises.lookup('example.org', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});

dnsPromises.lookupService(address, port)#

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

如果 address 不是一个有效的 IP 地址,将抛出 TypeErrorport 将被强制转换为一个数字。如果它不是一个合法的端口,将抛出 TypeError

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

import dnsPromises from 'node:dns/promises';
const result = await dnsPromises.lookupService('127.0.0.1', 22);

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

dnsPromises.resolve(hostname[, rrtype])#

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

使用 DNS 协议将主机名(例如 'nodejs.org')解析为资源记录数组。成功时,Promise 解析为一个资源记录数组。单个结果的类型和结构根据 rrtype 而变化。

rrtyperecords 包含结果类型快捷方法
'A'IPv4 地址(默认)<string>dnsPromises.resolve4()
'AAAA'IPv6 地址<string>dnsPromises.resolve6()
'ANY'任何记录<Object>dnsPromises.resolveAny()
'CAA'CA 授权记录<Object>dnsPromises.resolveCaa()
'CNAME'规范名称记录<string>dnsPromises.resolveCname()
'MX'邮件交换记录<Object>dnsPromises.resolveMx()
'NAPTR'名称权威指针记录<Object>dnsPromises.resolveNaptr()
'NS'名称服务器记录<string>dnsPromises.resolveNs()
'PTR'指针记录<string>dnsPromises.resolvePtr()
'SOA'起始授权机构记录<Object>dnsPromises.resolveSoa()
'SRV'服务记录<Object>dnsPromises.resolveSrv()
'TLSA'证书关联<Object>dnsPromises.resolveTlsa()
'TXT'文本记录<string[]>dnsPromises.resolveTxt()

出错时,Promise 会被一个 Error 对象拒绝,其中 err.codeDNS 错误代码之一。

dnsPromises.resolve4(hostname[, options])#

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

使用 DNS 协议解析 hostname 的 IPv4 地址(A 记录)。成功时,Promise 解析为一个 IPv4 地址数组(例如 ['74.125.79.104', '74.125.79.105', '74.125.79.106'])。

dnsPromises.resolve6(hostname[, options])#

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

使用 DNS 协议解析 hostname 的 IPv6 地址(AAAA 记录)。成功时,Promise 解析为一个 IPv6 地址数组。

dnsPromises.resolveAny(hostname)#

使用 DNS 协议解析所有记录(也称为 ANY* 查询)。成功时,Promise 解析为一个包含各种类型记录的数组。每个对象都有一个 type 属性,指示当前记录的类型。并且根据 type,对象上还会存在其他属性。

类型属性
'A'address/ttl
'AAAA'address/ttl
'CNAME'value
'MX'请参阅 dnsPromises.resolveMx()
'NAPTR'请参阅 dnsPromises.resolveNaptr()
'NS'value
'PTR'value
'SOA'请参阅 dnsPromises.resolveSoa()
'SRV'请参阅 dnsPromises.resolveSrv()
'TLSA'请参阅 dnsPromises.resolveTlsa()
'TXT'这种类型的记录包含一个名为 entries 的数组属性,它引用了 dnsPromises.resolveTxt(),例如 { entries: ['...'], type: 'TXT' }

以下是结果对象的示例:

[ { 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 } ] 

dnsPromises.resolveCaa(hostname)#

使用 DNS 协议解析 hostnameCAA 记录。成功时,Promise 解析为一个对象数组,其中包含可用于 hostname 的证书颁发机构授权记录(例如 [{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}])。

dnsPromises.resolveCname(hostname)#

使用 DNS 协议解析 hostnameCNAME 记录。成功时,Promise 解析为一个可用于 hostname 的规范名称记录数组(例如 ['bar.example.com'])。

dnsPromises.resolveMx(hostname)#

使用 DNS 协议解析 hostname 的邮件交换记录(MX 记录)。成功时,Promise 解析为一个对象数组,每个对象都包含 priorityexchange 属性(例如 [{priority: 10, exchange: 'mx.example.com'}, ...])。

dnsPromises.resolveNaptr(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
} 

dnsPromises.resolveNs(hostname)#

使用 DNS 协议解析 hostname 的名称服务器记录(NS 记录)。成功时,Promise 解析为一个可用于 hostname 的名称服务器记录数组(例如 ['ns1.example.com', 'ns2.example.com'])。

dnsPromises.resolvePtr(hostname)#

使用 DNS 协议解析 hostname 的指针记录(PTR 记录)。成功时,Promise 解析为一个包含应答记录的字符串数组。

dnsPromises.resolveSoa(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
} 

dnsPromises.resolveSrv(hostname)#

使用 DNS 协议解析 hostname 的服务记录(SRV 记录)。成功时,Promise 解析为一个具有以下属性的对象数组:

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

dnsPromises.resolveTlsa(hostname)#

使用 DNS 协议解析 hostname 的证书关联记录(TLSA 记录)。成功时,Promise 解析为一个具有以下属性的对象数组:

  • certUsage
  • selector
  • match
  • data
{
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer]
} 

dnsPromises.resolveTxt(hostname)#

使用 DNS 协议解析 hostname 的文本查询(TXT 记录)。成功时,Promise 解析为一个二维数组,其中包含 hostname 可用的文本记录(例如 [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ])。每个子数组包含一条记录的 TXT 块。根据用例,这些块可以连接在一起或分开处理。

dnsPromises.reverse(ip)#

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

出错时,Promise 会被一个 Error 对象拒绝,其中 err.codeDNS 错误代码之一。

dnsPromises.setDefaultResultOrder(order)#

  • order <string> 必须是 'ipv4first''ipv6first''verbatim'

设置 dns.lookup()dnsPromises.lookup()order 的默认值。该值可以是:

  • ipv4first:将默认 order 设置为 ipv4first
  • ipv6first:将默认 order 设置为 ipv6first
  • verbatim:将默认 order 设置为 verbatim

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

dnsPromises.getDefaultResultOrder()#

获取 dnsOrder 的值。

dnsPromises.setServers(servers)#

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

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

如果提供了无效地址,将抛出错误。

在 DNS 查询进行中时,不得调用 dnsPromises.setServers() 方法。

此方法的工作方式很像 resolve.conf。也就是说,如果尝试使用提供的第一个服务器解析导致 NOTFOUND 错误,resolve() 方法将不会尝试使用后续提供的服务器进行解析。只有当较早的服务器超时或导致其他错误时,才会使用备用 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 的线程池。

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

它们不使用与 dns.lookup() 相同的配置文件集。例如,它们不使用 /etc/hosts 中的配置。