- assert断言
- async_hooks异步钩子
- buffer缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process子进程
- cluster集群
- CLI命令行
- console控制台
- Corepack核心包
- crypto加密
- debugger调试器
- deprecation弃用
- dgram数据报
- diagnostics_channel诊断通道
- dns域名服务器
- domain域
- Error错误
- events事件触发器
- fs文件系统
- global全局变量
- http超文本传输协议
- http2超文本传输协议2.0
- https安全超文本传输协议
- inspector检查器
- Intl国际化
- module模块
- module/cjsCommonJS模块
- module/esmECMAScript模块
- module/package包模块
- net网络
- os操作系统
- path路径
- perf_hooks性能钩子
- policy安全策略
- process进程
- punycode域名代码
- querystring查询字符串
- readline逐行读取
- repl交互式解释器
- report诊断报告
- stream流
- string_decoder字符串解码器
- timers定时器
- tls安全传输层
- trace_events跟踪事件
- tty终端
- url网址
- util实用工具
- v8引擎
- vm虚拟机
- wasi网络汇编系统接口
- worker_threads工作线程
- zlib压缩
Node.js v14.21.1 文档
- Node.js 14.21.1
-
►
目录
- dns 域名服务器
dns.Resolver
类dns.getServers()
dns.lookup(hostname[, options], callback)
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.resolveCaa(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.setDefaultResultOrder(order)
dns.setServers(servers)
- Promise 形式的 API
dnsPromises.Resolver
类resolver.cancel()
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.resolveCaa(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.setDefaultResultOrder(order)
dnsPromises.setServers(servers)
- 错误码
- 实现的注意事项
- dns 域名服务器
-
►
索引
- assert 断言
- async_hooks 异步钩子
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- policy 安全策略
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- stream 流
- string_decoder 字符串解码器
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- ► 其他版本
- 文档搜索
目录
- dns 域名服务器
dns.Resolver
类dns.getServers()
dns.lookup(hostname[, options], callback)
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.resolveCaa(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.setDefaultResultOrder(order)
dns.setServers(servers)
- Promise 形式的 API
dnsPromises.Resolver
类resolver.cancel()
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.resolveCaa(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.setDefaultResultOrder(order)
dnsPromises.setServers(servers)
- 错误码
- 实现的注意事项
dns 域名服务器#
源代码: lib/dns.js
dns
模块启用了名称解析。
例如,使用它来查找主机名的 IP 地址。
尽管以域名系统命名,但它并不总是使用域名系统协议进行查找。
dns.lookup()
使用操作系统工具来执行名称解析。
它可能不需要执行任何网络通信。
要像同一系统上的其他应用程序那样执行名称解析,则使用 dns.lookup()
。
const dns = require('dns');
dns.lookup('example.org', (err, address, family) => {
console.log('address: %j family: IPv%s', address, family);
});
// address: "93.184.216.34" family: IPv4
dns
模块中的所有其他函数都连接到实际的域名系统服务器以执行名称解析。
它们将始终使用网络来执行域名系统查询。
这些函数不使用 dns.lookup()
使用的同一组配置文件(例如 /etc/hosts
)。
使用这些函数始终执行域名系统查询,绕过其他名称解析工具。
const dns = require('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
类#
域名系统请求的独立解析器。
创建新的解析器使用默认的服务器设置。
使用 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.resolveCaa()
resolver.resolveCname()
resolver.resolveMx()
resolver.resolveNaptr()
resolver.resolveNs()
resolver.resolvePtr()
resolver.resolveSoa()
resolver.resolveSrv()
resolver.resolveTxt()
resolver.reverse()
resolver.setServers()
Resolver([options])
#
创建新的解析器。
options
<Object>
resolver.cancel()
#
取消此解析器进行的所有未完成的域名系统查询。
相应的回调将被调用,错误码为 ECANCELLED
。
resolver.setLocalAddress([ipv4][, ipv6])
#
解析器实例将从指定的 IP 地址发送其请求。 这允许程序在多宿主系统上使用时指定出站接口。
如果未指定 v4 或 v6 地址,则设置为默认地址,操作系统将自动选择本地地址。
解析器在向 IPv4域名系统服务器发出请求时将使用 v4 本地地址,在向 IPv6域名系统服务器发出请求时将使用 v6 本地地址。
解析请求的 rrtype
对使用的本地地址没有影响。
dns.getServers()
#
- 返回: <string[]>
返回 IP 地址字符串的数组,根据 RFC 5952 格式化,当前配置为用于 DNS 解析。 如果使用自定义端口,则字符串将包含端口部分。
[
'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
(地址已重新排序),但预计在不久的将来会发生变化。 默认值可使用dns.setDefaultResultOrder()
或--dns-result-order
进行配置。 新代码应使用{ verbatim: true }
。
callback
<Function>
将主机名(例如 'nodejs.org'
)解析为第一个找到的 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()
不一定与域名系统协议有任何关系。
该实现使用了一个操作系统工具,可以将名称与地址相关联,反之亦然。
这种实现会对任何 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('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
// 当 options.all 为真时,结果将是数组。
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}]
如果此方法作为其 util.promisify()
版本被调用,并且 all
未设置为 true
,则它为具有 address
和 family
属性的 Object
返回 Promise
。
支持的 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
<string>port
<number>callback
<Function>
使用操作系统的底层 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()
版本被调用,则其将为具有 hostname
和 service
属性的 Object
返回 Promise
。
dns.resolve(hostname[, rrtype], callback)
#
hostname
<string> 要解析的主机名。rrtype
<string> 资源记录类型。 默认值:'A'
。callback
<Function>err
<Error>records
<string[]> | <Object[]> | <Object>
使用域名系统协议将主机名(例如 'nodejs.org'
)解析为资源记录数组。
callback
函数有参数 (err, records)
。
当成功时,records
将是资源记录数组。
个别结果的类型和结构因 rrtype
而异:
rrtype | records 包含 | 结果的类型 | 快捷方法 |
---|---|---|---|
'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() |
'TXT' | 文本记录 | <string[]> | dns.resolveTxt() |
dns.resolve4(hostname[, options], callback)
#
hostname
<string> 要解析的主机名。options
<Object>ttl
<boolean> 检索每条记录的生存时间值 (TTL)。 当为true
时,回调接收{ address: '1.2.3.4', ttl: 60 }
对象数组而不是字符串数组,TTL 以秒表示。
callback
<Function>err
<Error>addresses
<string[]> | <Object[]>
使用域名系统协议为 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>err
<Error>addresses
<string[]> | <Object[]>
使用域名系统协议为 hostname
解析 IPv6 地址(AAAA
记录)。
传给 callback
函数的 addresses
参数将包含 IPv6 地址数组。
dns.resolveAny(hostname, callback)
#
hostname
<string>callback
<Function>err
<Error>ret
<Object[]>
使用域名系统协议解析所有记录(也称为 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() |
'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 } ]
域名系统服务器运营商可以选择不响应 ANY
查询。
调用单个方法(如 dns.resolve4()
、dns.resolveMx()
等)可能会更好。
有关更多详细信息,请参阅 RFC 8482。
dns.resolveCname(hostname, callback)
#
hostname
<string>callback
<Function>err
<Error>addresses
<string[]>
使用域名系统协议为 hostname
解析 CNAME
记录。
传给 callback
函数的 addresses
参数将包含可用于 hostname
(例如 ['bar.example.com']
)的规范名称记录的数组。
dns.resolveCaa(hostname, callback)
#
hostname
<string>callback
<Function>err
<Error>records
<Object[]>
使用域名系统协议为 hostname
解析 CAA
记录。
传给 callback
函数的 addresses
参数将包含可用于 hostname
(例如 [{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]
)的证书颁发机构授权记录的数组。
dns.resolveMx(hostname, callback)
#
hostname
<string>callback
<Function>err
<Error>addresses
<Object[]>
使用域名系统协议解析 hostname
的邮件交换记录(MX
记录)。
传给 callback
函数的 addresses
参数将包含其中包含 priority
和 exchange
属性(例如 [{priority: 10, exchange: 'mx.example.com'}, ...]
)的对象数组。
dns.resolveNaptr(hostname, callback)
#
hostname
<string>callback
<Function>err
<Error>addresses
<Object[]>
使用域名系统协议为 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)
#
hostname
<string>callback
<Function>err
<Error>addresses
<string[]>
使用域名系统协议为 hostname
解析名称服务器记录(NS
记录)。
传给 callback
函数的 addresses
参数将包含可用于 hostname
(例如 ['ns1.example.com', 'ns2.example.com']
)的名称服务器记录数组。
dns.resolvePtr(hostname, callback)
#
hostname
<string>callback
<Function>err
<Error>addresses
<string[]>
使用域名系统协议解析 hostname
的指针记录(PTR
记录)。
传给 callback
函数的 addresses
参数将是包含回复记录的字符串数组。
dns.resolveSoa(hostname, callback)
#
hostname
<string>callback
<Function>
使用域名系统协议来解析 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)
#
hostname
<string>callback
<Function>err
<Error>addresses
<Object[]>
使用域名系统协议解析 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[][]>
使用域名系统协议为 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[]>
执行反向域名系统查询,将 IPv4 或 IPv6 地址解析为主机名数组。
dns.setDefaultResultOrder(order)
#
order
<string> 必须是'ipv4first'
或'verbatim'
。
在 dns.lookup()
和 dnsPromises.lookup()
中设置 verbatim
的默认值。
该值可能是:
ipv4first
: 设置默认的verbatim
为false
。verbatim
: 设置默认的verbatim
为true
。
默认为 ipv4first
,并且 dns.setDefaultResultOrder()
的优先级高于 --dns-result-order
。
当使用工作线程时,主线程中的 dns.setDefaultResultOrder()
不会影响工作线程中的默认 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.setServers()
方法。
dns.setServers()
方法仅影响 dns.resolve()
、dns.resolve*()
和 dns.reverse()
(特别是不影响 dns.lookup()
)。
此方法的工作方式与 resolve.conf 非常相似。
也就是说,如果尝试使用提供的第一个服务器进行解析导致 NOTFOUND
错误,则 resolve()
方法将不会尝试使用提供的后续服务器进行解析。
仅当较早的域名系统服务器超时或导致其他错误时,才会使用后备域名系统服务器。
Promise 形式的 API#
dns.promises
API 提供了一组替代的异步 DNS 方法,这些方法返回 Promise
对象而不是使用回调。
API 可通过 require('dns').promises
访问。
dnsPromises.Resolver
类#
域名系统请求的独立解析器。
创建新的解析器使用默认的服务器设置。
使用 resolver.setServers()
设置用于解析器的服务器不会影响其他解析器:
const { Resolver } = require('dns').promises;
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);
// 此请求将使用 4.4.4.4 的服务器,与全局设置无关。
resolver.resolve4('example.org').then((addresses) => {
// ...
});
// 或者,可以使用 async-await 风格编写相同的代码。
(async function() {
const addresses = await resolver.resolve4('example.org');
})();
来自 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()
#
取消此解析器进行的所有未完成的域名系统查询。
相应的 promise 将使用错误码 ECANCELLED
拒绝,。
dnsPromises.getServers()
#
- 返回: <string[]>
返回 IP 地址字符串的数组,根据 RFC 5952 格式化,当前配置为用于 DNS 解析。 如果使用自定义端口,则字符串将包含端口部分。
[
'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> 记录族。 必须是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('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}]
});
dnsPromises.lookupService(address, port)
#
使用操作系统的底层 getnameinfo
实现将给定的 address
和 port
解析为主机名和服务。
如果 address
不是有效的 IP 地址,则会抛出 TypeError
。
port
将被强制为数字。
如果不是合法的端口,则会抛出 TypeError
。
当出错时,Promise
使用 Error
对象拒绝,其中 err.code
是错误码。
const dnsPromises = require('dns').promises;
dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
console.log(result.hostname, result.service);
// 打印: localhost ssh
});
dnsPromises.resolve(hostname[, rrtype])
#
使用域名系统协议将主机名(例如 'nodejs.org'
)解析为资源记录数组。
当成功时,Promise
使用资源记录数组解决。
个别结果的类型和结构因 rrtype
而异:
rrtype | records 包含 | 结果的类型 | 快捷方法 |
---|---|---|---|
'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() |
'TXT' | 文本记录 | <string[]> | dnsPromises.resolveTxt() |
当出错时,Promise
使用 Error
对象拒绝,其中 err.code
是 DNS 错误码 之一。
dnsPromises.resolve4(hostname[, options])
#
hostname
<string> 要解析的主机名。options
<Object>ttl
<boolean> 检索每条记录的生存时间值 (TTL)。 当为true
时,Promise
使用{ address: '1.2.3.4', ttl: 60 }
对象数组而不是字符串数组进行解决,TTL 以秒表示。
使用域名系统协议为 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 以秒表示。
使用域名系统协议为 hostname
解析 IPv6 地址(AAAA
记录)。
当成功时,Promise
使用 IPv6 地址数组解决。
dnsPromises.resolveAny(hostname)
#
hostname
<string>
使用域名系统协议解析所有记录(也称为 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() |
'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)
#
hostname
<string>
使用域名系统协议为 hostname
解析 CAA
记录。
当成功时,Promise
使用包含可用于 hostname
(例如 [{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]
)的可用证书颁发机构授权记录的对象数组进行解决。
dnsPromises.resolveCname(hostname)
#
hostname
<string>
使用域名系统协议为 hostname
解析 CNAME
记录。
当成功时,Promise
使用 hostname
可用的规范名称记录数组(例如 ['bar.example.com']
)进行解决。
dnsPromises.resolveMx(hostname)
#
hostname
<string>
使用域名系统协议解析 hostname
的邮件交换记录(MX
记录)。
当成功时,Promise
使用包含 priority
和 exchange
属性(例如 [{priority: 10, exchange: 'mx.example.com'}, ...]
)的对象数组进行解决。
dnsPromises.resolveNaptr(hostname)
#
hostname
<string>
使用域名系统协议为 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)
#
hostname
<string>
使用域名系统协议为 hostname
解析名称服务器记录(NS
记录)。
当成功时,Promise
使用可用于 hostname
的名称服务器记录数组(例如 ['ns1.example.com', 'ns2.example.com']
)进行解决。
dnsPromises.resolvePtr(hostname)
#
hostname
<string>
使用域名系统协议解析 hostname
的指针记录(PTR
记录)。
当成功时,Promise
使用包含回复记录的字符串数组进行解决。
dnsPromises.resolveSoa(hostname)
#
hostname
<string>
使用域名系统协议来解析 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)
#
hostname
<string>
使用域名系统协议解析 hostname
的服务记录(SRV
记录)。
当成功时,Promise
使用具有以下属性的对象数组进行解决:
priority
weight
port
name
{
priority: 10,
weight: 5,
port: 21223,
name: 'service.example.com'
}
dnsPromises.resolveTxt(hostname)
#
hostname
<string>
使用域名系统协议为 hostname
解析文本查询(TXT
记录)。
当成功时,Promise
使用可用于 hostname
(例如 [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]
)的文本记录的二维数组进行解决。
每个子数组包含一条记录的 TXT 块。
根据用例,这些可以连接在一起或单独处理。
dnsPromises.reverse(ip)
#
ip
<string>
执行反向域名系统查询,将 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
。
默认为 ipv4first
,并且 dnsPromises.setDefaultResultOrder()
的优先级高于 --dns-result-order
。
当使用工作线程时,主线程中的 dnsPromises.setDefaultResultOrder()
不会影响工作线程中的默认 dns 命令。
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',
]);
如果提供的地址无效,则会抛出错误。
在进行域名系统查询时不得调用 dnsPromises.setServers()
方法。
此方法的工作方式与 resolve.conf 非常相似。
也就是说,如果尝试使用提供的第一个服务器进行解析导致 NOTFOUND
错误,则 resolve()
方法将不会尝试使用提供的后续服务器进行解析。
仅当较早的域名系统服务器超时或导致其他错误时,才会使用后备域名系统服务器。
错误码#
每个域名系统查询都可以返回以下错误代码之一:
dns.NODATA
: 域名系统服务器返回没有数据的答案。dns.FORMERR
: 域名系统服务器声称查询格式错误。dns.SERVFAIL
: 域名系统服务器返回一般故障。dns.NOTFOUND
: 未找到域名。dns.NOTIMP
: 域名系统服务器未执行请求的操作。dns.REFUSED
: 域名系统服务器拒绝查询。dns.BADQUERY
: 域名系统查询格式错误。dns.BADNAME
: 主机名格式错误。dns.BADFAMILY
: 不支持的地址族。dns.BADRESP
: DNS 回复格式错误。dns.CONNREFUSED
: 无法联系域名系统服务器。dns.TIMEOUT
: 联系域名系统服务器时超时。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.lookup()
和各种 dns.resolve*()/dns.reverse()
函数具有将网络名称与网络地址相关联的相同目标(反之亦然),但它们的行为却大不相同。
这些差异可能会对 Node.js 程序的行为产生微妙但重要的影响。
dns.lookup()
#
在幕后,dns.lookup()
使用与大多数其他程序相同的操作系统设施。
例如,dns.lookup()
几乎总是以与 ping
命令相同的方式解析给定名称。
在大多数类似 POSIX 的操作系统上,可以通过更改 nsswitch.conf(5)
和/或 resolv.conf(5)
中的设置来修改 dns.lookup()
函数的行为,但更改这些文件将更改在同一操作系统上运行的所有其他程序的行为。
尽管对 dns.lookup()
的调用从 JavaScript 的角度来看是异步的,但它被实现为对运行在 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)
,其总是在网络上执行域名系统查询。
这种网络通信总是异步完成的,不使用 libuv 的线程池。
因此,这些函数不会对发生在 libuv 线程池上的其他处理产生与 dns.lookup()
相同的负面影响。
它们使用的配置文件集与 dns.lookup()
使用的配置文件集不同。
例如,它们不使用 /etc/hosts
的配置。