目录

• dns（域名服务器）

  • dns.Resolver 类

    • resolver.cancel()
  • dns.getServers()

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

    • 支持的 getaddrinfo
  • dns.lookupService(address, port, callback)
  • dns.resolve(hostname[, rrtype], callback)
  • dns.resolve4(hostname[, options], callback)
  • dns.resolve6(hostname[, options], callback)
  • dns.resolveAny(hostname, callback)
  • dns.resolveCname(hostname, callback)
  • dns.resolveMx(hostname, callback)
  • dns.resolveNaptr(hostname, callback)
  • dns.resolveNs(hostname, callback)
  • dns.resolvePtr(hostname, callback)
  • dns.resolveSoa(hostname, callback)
  • dns.resolveSrv(hostname, callback)
  • dns.resolveTxt(hostname, callback)
  • dns.reverse(ip, callback)
  • dns.setServers(servers)

  • Promise 形式的 API

    • dnsPromises.Resolver 类
    • dnsPromises.getServers()
    • dnsPromises.lookup(hostname[, options])
    • dnsPromises.lookupService(address, port)
    • dnsPromises.resolve(hostname[, rrtype])
    • dnsPromises.resolve4(hostname[, options])
    • dnsPromises.resolve6(hostname[, options])
    • dnsPromises.resolveAny(hostname)
    • dnsPromises.resolveCname(hostname)
    • dnsPromises.resolveMx(hostname)
    • dnsPromises.resolveNaptr(hostname)
    • dnsPromises.resolveNs(hostname)
    • dnsPromises.resolvePtr(hostname)
    • dnsPromises.resolveSoa(hostname)
    • dnsPromises.resolveSrv(hostname)
    • dnsPromises.resolveTxt(hostname)
    • dnsPromises.reverse(ip)
    • dnsPromises.setServers(servers)
  • 错误码

  • 实现的注意事项

    • dns.lookup()
    • dns.resolve()、dns.resolve*() 与 dns.reverse()

dns（域名服务器）#

中英对照提交修改

dns 模块用于启用名称解析。 例如，使用它来查找主机名的 IP 地址。

尽管以域名系统（DNS）命名，但它并不总是使用 DNS 协议进行查找。 dns.lookup() 使用操作系统功能来执行名称解析。 它可能不需要执行任何网络通信。 希望以与同一操作系统上其他应用程序相同的方式执行名称解析的开发者应使用 dns.lookup()。

const dns = require('dns');

dns.lookup('example.org', (err, address, family) => {
console.log('地址: %j 地址族: IPv%s', address, family);
});
// 地址: "93.184.216.34" 地址族: IPv4

dns 模块中的所有其他函数都连接到实际的 DNS 服务器以执行名称解析。 它们将会始终使用网络执行 DNS 查询。 这些函数不使用与 dns.lookup() 使用的同一组配置文件（例如 /etc/hosts）。 这些函数应由不想使用底层操作系统的功能进行名称解析、而希望始终执行 DNS 查询的开发者使用。

const dns = require('dns');

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

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

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

有关更多信息，参阅实现的注意事项。

dns.Resolver 类#

中英对照提交修改

DNS 请求的独立解析程序。

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

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

// 此请求将使用 4.4.4.4 中的服务器，与全局设置无关。
resolver.resolve4('example.org', (err, addresses) => {
  // ...
});

可以使用的 dns 模块的方法如下：

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

resolver.cancel()#

中英对照提交修改

取消此解析程序所做的所有未完成的DNS查询。 使用错误码 ECANCELLED 调用相应的回调。

dns.getServers()#

中英对照提交修改

• 返回: <string[]>

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

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

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

中英对照提交修改

• hostname <string>

• options <integer> | <Object>

  • family <integer> 记录的地址族。必须为 4、 6 或 0。0 值表示返回 IPv4 和 IPv6 地址。默认值: 0。
  • hints <number> 一个或多个受支持的 getaddrinfo 标志。可以通过按位 OR 运算它们的值来传递多个标志。
  • all <boolean> 当为 true 时，则回调将会返回数组中所有已解析的地址。否则，返回单个地址。默认值： false。
  • verbatim <boolean> 当为 true 时，则回调按 DNS 解析器返回的顺序接收 IPv4 和 IPv6 地址。当为 false 时，则 IPv4 地址放在 IPv6 地址之前。 默认值: 当前为 false（地址已重新排序）但预计在不久的将来会发生变化。新代码应使用 { verbatim: true }。

• callback <Function>

  • err <Error>
  • address <string> IPv4 或 IPv6 地址的字符串表示形式。
  • family <integer> 4 或 6，表示 address 的地址族，如果地址不是 IPv4 或 IPv6 地址，则为 0。0 可能是操作系统使用的名称解析服务中的错误的指示符。

解析主机名（例如：'www.haotouying.com'）为第一个找到的 A（IPv4）或 AAAA（IPv6）记录。 所有的 option 属性都是可选的。 如果 options 是整数，则只能是 4 或 6。 如果 options 没有被提供，则 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('dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('地址: %j 地址族: IPv%s', address, family));
// 地址: "2606:2800:220:1:248:1893:25c8:1946" 地址族: IPv6

// 当 options.all 为 true 时，则结果将会是一个数组。
options.all = true;
dns.lookup('example.com', options, (err, addresses) =>
  console.log('地址: %j', addresses));
// 地址: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]

如果调用此方法的 util.promisify() 化的版本，并且 all 未设置为 true，则它返回的 Promise 会返回一个具有 address 和 family 属性的对象。

支持的 getaddrinfo#

中英对照提交修改

以下内容可以作为 hints 标志传给 dns.lookup()。

• dns.ADDRCONFIG: 返回当前系统支持的地址类型。例如，如果当前系统至少配置了一个 IPv4 地址，则返回 IPv4 地址。不考虑回环地址。
• dns.V4MAPPED: 如果指定了 IPv6 地址族，但是没有找到 IPv6 地址，则返回 IPv4 映射的 IPv6 地址。在有些操作系统中不支持（例如 FreeBSD 10.1）。

dns.lookupService(address, port, callback)#

中英对照提交修改

• address <string>
• port <number>

• callback <Function>

  • err <Error>
  • hostname <string> 例如 www.haotouying.com。
  • service <string> 例如 http。

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

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

出错情况下， err 是一个 Error 对象，其中 err.code 是错误码。

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

如果调用此方法的 util.promisify() 化的版本，则它返回的 Promise 会返回一个具有 hostname 和 service 属性的 Object。

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

中英对照提交修改

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

• callback <Function>

  • err <Error>
  • records <string[]> | <Object[]> | <Object>

使用 DNS 协议将主机名（例如 'www.haotouying.com'）解析为一个资源记录的数组。 callback 函数的参数为 (err, records)。 当成功时， records 将会是一个资源记录的数组。 它的类型和结构取决于 rrtype：

rrtype	records 包含	结果的类型	快捷方法
'A'	IPv4 地址 (默认)	<string>	dns.resolve4()
'AAAA'	IPv6 地址	<string>	dns.resolve6()
'ANY'	任何记录	<Object>	dns.resolveAny()
'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()
'TXT'	文本记录	<string[]>	dns.resolveTxt()

当出错时， err 是一个 Error 对象，其中 err.code 是 DNS 错误码的一种。

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

中英对照提交修改

• hostname <string> 需要解析的主机名。

• options <Object>

  • ttl <boolean> 记录每一条记录的存活次数 (TTL)。当为 true 时，回调会接收一个带有 TTL 秒数记录的类似 { address: '1.2.3.4', ttl: 60 } 对象的数组，而不是字符串的数组。

• callback <Function>

  • err <Error>
  • addresses <string[]> | <Object[]>

使用 DNS 协议为 hostname 解析 IPv4 地址（A 记录）。 adresses 参数是传给 callback 函数的 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 时，回调会接收一个带有 TTL 秒数记录的类似 { address: '0:1:2:3:4:5:6:7', ttl: 60 } 对象的数组，而不是字符串的数组。

• callback <Function>

  • err <Error>
  • addresses <string[]> | <Object[]>

使用 DNS 协议为 hostname 解析 IPv6 地址（AAAA 记录）。 adresses 参数是传给 callback 函数的 IPv6 地址数组。

dns.resolveAny(hostname, callback)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • ret <Object[]>

使用 DNS 协议解析所有记录（也称为 ANY 或 * 查询）。 传给 callback 函数的 ret 参数将会是一个包含各种类型记录的数组。 每个对象都有一个 callback 属性，表明当前记录的类型。 根据 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()
'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)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • addresses <string[]>

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

dns.resolveMx(hostname, callback)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • addresses <Object[]>

使用 DNS 协议为 hostname 解析邮件交换记录（MX 记录）。 传给 callback 函数的 adresses 参数将会包含具有 priority 和 exchange 属性的对象的数组（例如：[{priority: 10, exchange: 'mx.example.com'}, ...]）。

dns.resolveNaptr(hostname, callback)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • addresses <Object[]>

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

• 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)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • addresses <string[]>

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

dns.resolvePtr(hostname, callback)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • addresses <string[]>

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

dns.resolveSoa(hostname, callback)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • address <Object>

使用 DNS 协议为 hostname 解析开始权限记录（SOA 记录）。 传给 callback 函数的 addresses 参数将会是一个具有以下属性的对象：

• 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)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • addresses <Object[]>

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

• priority
• weight
• port
• name

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

dns.resolveTxt(hostname, callback)#

中英对照提交修改

• hostname <string>

• callback <Function>

  • err <Error>
  • records <string[][]>

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

dns.reverse(ip, callback)#

中英对照提交修改

• ip <string>

• callback <Function>

  • err <Error>
  • hostnames <string[]>

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

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

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'
]);

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

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

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

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

Promise 形式的 API#

暂无中英对照提交修改

The dns.promises API provides an alternative set of asynchronous DNS methods that return Promise objects rather than using callbacks. The API is accessible via require('dns').promises.

dnsPromises.Resolver 类#

暂无中英对照提交修改

An independent resolver for DNS requests.

Creating a new resolver uses the default server settings. Setting the servers used for a resolver using resolver.setServers() does not affect other resolvers:

const { Resolver } = require('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');
})();

The following methods from the dnsPromises API are available:

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

dnsPromises.getServers()#

暂无中英对照提交修改

• Returns: <string[]>

Returns an array of IP address strings, formatted according to RFC 5952, that are currently configured for DNS resolution. A string will include a port section if a custom port is used.

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

dnsPromises.lookup(hostname[, options])#

暂无中英对照提交修改

• hostname <string>

• options <integer> | <Object>

  • family <integer> The record family. Must be 4, 6, or 0. The value 0 indicates that IPv4 and IPv6 addresses are both returned. Default: 0.
  • hints <number> One or more supported getaddrinfo flags. Multiple flags may be passed by bitwise ORing their values.
  • all <boolean> When true, the Promise is resolved with all addresses in an array. Otherwise, returns a single address. Default: false.
  • verbatim <boolean> When true, the Promise is resolved with IPv4 and IPv6 addresses in the order the DNS resolver returned them. When false, IPv4 addresses are placed before IPv6 addresses. Default: currently false (addresses are reordered) but this is expected to change in the not too distant future. New code should use { verbatim: true }.

Resolves a host name (e.g. 'nodejs.org') into the first found A (IPv4) or AAAA (IPv6) record. All option properties are optional. If options is an integer, then it must be 4 or 6 – if options is not provided, then IPv4 and IPv6 addresses are both returned if found.

With the all option set to true, the Promise is resolved with addresses being an array of objects with the properties address and family.

On error, the Promise is rejected with an Error object, where err.code is the error code. Keep in mind that err.code will be set to 'ENOTFOUND' not only when the host name does not exist but also when the lookup fails in other ways such as no available file descriptors.

dnsPromises.lookup() does not necessarily have anything to do with the DNS protocol. The implementation uses an operating system facility that can associate names with addresses, and vice versa. This implementation can have subtle but important consequences on the behavior of any Node.js program. Please take some time to consult the Implementation considerations section before using dnsPromises.lookup().

Example usage:

const dns = require('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}]
});

dnsPromises.lookupService(address, port)#

暂无中英对照提交修改

• address <string>
• port <number>

Resolves the given address and port into a host name and service using the operating system's underlying getnameinfo implementation.

If address is not a valid IP address, a TypeError will be thrown. The port will be coerced to a number. If it is not a legal port, a TypeError will be thrown.

On error, the Promise is rejected with an Error object, where err.code is the error code.

const dnsPromises = require('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> Host name to resolve.
• rrtype <string> Resource record type. Default: 'A'.

Uses the DNS protocol to resolve a host name (e.g. 'nodejs.org') into an array of the resource records. When successful, the Promise is resolved with an array of resource records. The type and structure of individual results vary based on rrtype:

rrtype	records contains	Result type	Shorthand method
'A'	IPv4 addresses (default)	<string>	dnsPromises.resolve4()
'AAAA'	IPv6 addresses	<string>	dnsPromises.resolve6()
'ANY'	any records	<Object>	dnsPromises.resolveAny()
'CNAME'	canonical name records	<string>	dnsPromises.resolveCname()
'MX'	mail exchange records	<Object>	dnsPromises.resolveMx()
'NAPTR'	name authority pointer records	<Object>	dnsPromises.resolveNaptr()
'NS'	name server records	<string>	dnsPromises.resolveNs()
'PTR'	pointer records	<string>	dnsPromises.resolvePtr()
'SOA'	start of authority records	<Object>	dnsPromises.resolveSoa()
'SRV'	service records	<Object>	dnsPromises.resolveSrv()
'TXT'	text records	<string[]>	dnsPromises.resolveTxt()

On error, the Promise is rejected with an Error object, where err.code is one of the DNS error codes.

dnsPromises.resolve4(hostname[, options])#

暂无中英对照提交修改

• hostname <string> Host name to resolve.

• options <Object>

  • ttl <boolean> Retrieve the Time-To-Live value (TTL) of each record. When true, the Promise is resolved with an array of { address: '1.2.3.4', ttl: 60 } objects rather than an array of strings, with the TTL expressed in seconds.

Uses the DNS protocol to resolve IPv4 addresses (A records) for the hostname. On success, the Promise is resolved with an array of IPv4 addresses (e.g. ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dnsPromises.resolve6(hostname[, options])#

暂无中英对照提交修改

• hostname <string> Host name to resolve.

• options <Object>

  • ttl <boolean> Retrieve the Time-To-Live value (TTL) of each record. When true, the Promise is resolved with an array of { address: '0:1:2:3:4:5:6:7', ttl: 60 } objects rather than an array of strings, with the TTL expressed in seconds.

Uses the DNS protocol to resolve IPv6 addresses (AAAA records) for the hostname. On success, the Promise is resolved with an array of IPv6 addresses.

dnsPromises.resolveAny(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve all records (also known as ANY or * query). On success, the Promise is resolved with an array containing various types of records. Each object has a property type that indicates the type of the current record. And depending on the type, additional properties will be present on the object:

Type	Properties
'A'	address/ttl
'AAAA'	address/ttl
'CNAME'	value
'MX'	Refer to dnsPromises.resolveMx()
'NAPTR'	Refer to dnsPromises.resolveNaptr()
'NS'	value
'PTR'	value
'SOA'	Refer to dnsPromises.resolveSoa()
'SRV'	Refer to dnsPromises.resolveSrv()
'TXT'	This type of record contains an array property called entries which refers to dnsPromises.resolveTxt(), e.g. { entries: ['...'], type: 'TXT' }

Here is an example of the result object:

[ { 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.resolveCname(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve CNAME records for the hostname. On success, the Promise is resolved with an array of canonical name records available for the hostname (e.g. ['bar.example.com']).

dnsPromises.resolveMx(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve mail exchange records (MX records) for the hostname. On success, the Promise is resolved with an array of objects containing both a priority and exchange property (e.g. [{priority: 10, exchange: 'mx.example.com'}, ...]).

dnsPromises.resolveNaptr(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve regular expression based records (NAPTR records) for the hostname. On success, the Promise is resolved with an array of objects with the following properties:

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

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

dnsPromises.resolveNs(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve name server records (NS records) for the hostname. On success, the Promise is resolved with an array of name server records available for hostname (e.g. ['ns1.example.com', 'ns2.example.com']).

dnsPromises.resolvePtr(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve pointer records (PTR records) for the hostname. On success, the Promise is resolved with an array of strings containing the reply records.

dnsPromises.resolveSoa(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve a start of authority record (SOA record) for the hostname. On success, the Promise is resolved with an object with the following properties:

• 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)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve service records (SRV records) for the hostname. On success, the Promise is resolved with an array of objects with the following properties:

• priority
• weight
• port
• name

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

dnsPromises.resolveTxt(hostname)#

暂无中英对照提交修改

• hostname <string>

Uses the DNS protocol to resolve text queries (TXT records) for the hostname. On success, the Promise is resolved with a two-dimensional array of the text records available for hostname (e.g. [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Each sub-array contains TXT chunks of one record. Depending on the use case, these could be either joined together or treated separately.

dnsPromises.reverse(ip)#

暂无中英对照提交修改

• ip <string>

Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an array of host names.

On error, the Promise is rejected with an Error object, where err.code is one of the DNS error codes.

dnsPromises.setServers(servers)#

暂无中英对照提交修改

• servers <string[]> array of RFC 5952 formatted addresses

Sets the IP address and port of servers to be used when performing DNS resolution. The servers argument is an array of RFC 5952 formatted addresses. If the port is the IANA default DNS port (53) it can be omitted.

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

An error will be thrown if an invalid address is provided.

The dnsPromises.setServers() method must not be called while a DNS query is in progress.

This method works much like resolve.conf. That is, if attempting to resolve with the first server provided results in a NOTFOUND error, the resolve() method will not attempt to resolve with subsequent servers provided. Fallback DNS servers will only be used if the earlier ones time out or result in some other error.

错误码#

中英对照提交修改

每次 DNS 查询可能返回以下错误码之一:

• dns.NODATA: DNS 服务器返回没有数据。
• dns.FORMERR: DNS 服务器查询格式错误。
• dns.SERVFAIL: DNS 服务器返回常规失败。
• dns.NOTFOUND: 域名未找到。
• dns.NOIMP: 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 查询取消。

实现的注意事项#

中英对照提交修改

尽管 dns.lookup() 和各种变形的 dns.resolve*()/dns.reverse() 函数有相同的目标，将网络的名字与网络地址联系在一起（反之亦然），但它们的行为是完全不同的。 这些差异虽然微妙但对 Node.js 程序的行为有重大的影响。

dns.lookup()#

中英对照提交修改

在底层，dns.lookup() 使用的操作系统设施与大多数其他程序相同。 例如，dns.lookup() 几乎总是解析给定的主机名，与 ping 命令一样。 在大多数类 POSIX 操作系统中，dns.lookup() 函数的行为可以通过改变 nsswitch.conf(5) 和/或 resolv.conf(5) 的设置进行改变，但是需要注意改变这些文件就意味着改变所有正在这个操作系统中运行的所有程序的行为。

尽管以异步 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 的配置。