dnsPromises.lookup(hostname[, options])
hostname
<string>options
<integer> | <Object>family
<integer> 记录族。 必须是4
、6
或0
。 值0
表示同时返回 IPv4 和 IPv6 地址。 默认值:0
。hints
<number> 一个或多个受支持的getaddrinfo
标志。 多个标志可以通过按位OR
其值来传入。all
<boolean> 当为true
时,Promise
使用数组中的所有地址进行解决。 否则,返回单个地址。 默认值:false
。verbatim
<boolean> 当为true
时,Promise
使用按照 DNS 解析器返回的顺序使用 IPv4 和 IPv6 地址进行解决。 当为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()
不一定与域名系统协议有任何关系。
该实现使用一种操作系统工具,可以将名称与地址关联起来,反之亦然。
这种实现会对任何 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
});
// 当 options.all 为真时,结果将是数组。
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}]
});
hostname
<string>options
<integer> | <Object>family
<integer> The record family. Must be4
,6
, or0
. The value0
indicates that IPv4 and IPv6 addresses are both returned. Default:0
.hints
<number> One or more supportedgetaddrinfo
flags. Multiple flags may be passed by bitwiseOR
ing their values.all
<boolean> Whentrue
, thePromise
is resolved with all addresses in an array. Otherwise, returns a single address. Default:false
.verbatim
<boolean> Whentrue
, thePromise
is resolved with IPv4 and IPv6 addresses in the order the DNS resolver returned them. Whenfalse
, IPv4 addresses are placed before IPv6 addresses. Default: currentlyfalse
(addresses are reordered) but this is expected to change in the not too distant future. Default value is configurable usingdns.setDefaultResultOrder()
or--dns-result-order
. 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('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}]
});