- 断言测试
- 异步上下文跟踪
- 异步钩子
- 缓冲(Buffer)
- C++ 插件
- 使用 Node-API 的 C/C++ 插件
- C++ 嵌入 Node环境
- 子进程(Child processes)
- 集群(Cluster)
- 命令行选项
- 控制台(Console)
- 核心包(Corepack)
- 加密(Crypto)
- 调试器(Debugger)
- 已弃用的 API
- 诊断通道(Diagnostics Channel)
- 域名系统(DNS)
- 域(Domain)
- 错误(Errors)
- 事件(Events)
- 文件系统(File system)
- 全局变量(Globals)
- HTTP
- HTTP/2
- HTTPS
- 检查器(Inspector)
- 国际化
- 模块:CommonJS 模块
- 模块:ECMAScript 模块
- 模块:
node:module
API - 模块:packages 模块
- 网络(Net)
- 系统(OS)
- 路径(Path)
- 性能挂钩(Performance hooks)
- 性能挂钩(Permissions)
- 进程(Process)
- Punycode 国际化域名编码
- 查询字符串(Query strings)
- 命令行库(Readline)
- REPL 交互式编程环境
- 诊断报告
- 单个可执行应用程序
- Stream 流
- 字符串解码器
- 单元测试
- 定时器(Timers)
- 传输层安全/SSL
- 跟踪事件
- TTY
- UDP/数据报
- URL
- 实用程序
- V8
- 虚拟机
- WebAssembly
- Web加密 API(Web Crypto API)
- 网络流 API(Web Streams API)
- 工作线程(Worker threads)
- zlib
Node.js v18.18.2 文档
- Node.js v18.18.2
-
►
目录
- 域名系统
- 类:
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.getDefaultResultOrder()
dns.setServers(servers)
- DNS 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.getDefaultResultOrder()
dnsPromises.setServers(servers)
- 类:
- 错误代码
- 实施注意事项
- 类:
- 域名系统
-
►
索引
- 断言测试
- 异步上下文跟踪
- 异步钩子
- 缓冲(Buffer)
- C++ 插件
- 使用 Node-API 的 C/C++ 插件
- C++ 嵌入 Node环境
- 子进程(Child processes)
- 集群(Cluster)
- 命令行选项
- 控制台(Console)
- 核心包(Corepack)
- 加密(Crypto)
- 调试器(Debugger)
- 已弃用的 API
- 诊断通道(Diagnostics Channel)
- 域名系统(DNS)
- 域(Domain)
- 错误(Errors)
- 事件(Events)
- 文件系统(File system)
- 全局变量(Globals)
- HTTP
- HTTP/2
- HTTPS
- 检查器(Inspector)
- 国际化
- 模块:CommonJS 模块
- 模块:ECMAScript 模块
- 模块:
node:module
API - 模块:packages 模块
- 网络(Net)
- 系统(OS)
- 路径(Path)
- 性能挂钩(Performance hooks)
- 性能挂钩(Permissions)
- 进程(Process)
- Punycode 国际化域名编码
- 查询字符串(Query strings)
- 命令行库(Readline)
- REPL 交互式编程环境
- 诊断报告
- 单个可执行应用程序
- Stream 流
- 字符串解码器
- 单元测试
- 定时器(Timers)
- 传输层安全/SSL
- 跟踪事件
- TTY
- UDP/数据报
- URL
- 实用程序
- V8
- 虚拟机
- WebAssembly
- Web加密 API(Web Crypto API)
- 网络流 API(Web Streams API)
- 工作线程(Worker threads)
- zlib
- ► 其他版本
- ► 选项
目录
- 域名系统
- 类:
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.getDefaultResultOrder()
dns.setServers(servers)
- DNS 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.getDefaultResultOrder()
dnsPromises.setServers(servers)
- 类:
- 错误代码
- 实施注意事项
- 类:
域名系统#
源代码: lib/dns.js
node:dns
模块启用名称解析。例如,用它来查找主机名的 IP 地址。
尽管以域名系统 (DNS)命名,但它并不总是使用 DNS 协议进行查找。dns.lookup()
使用操作系统工具来执行名称解析。它可能不需要执行任何网络通信。要像同一系统上的其他应用程序那样执行名称解析,请使用dns.lookup()
。
const dns = require('node:dns');
dns.lookup('example.org', (err, address, family) => {
console.log('address: %j family: IPv%s', address, family);
});
// address: "93.184.216.34" family: IPv4
node:dns
模块中的所有其他函数都连接到实际的 DNS 服务器以执行名称解析。他们将始终使用网络来执行 DNS 查询。这些函数不使用
dns.lookup()
使用的同一组配置文件(例如/etc/hosts
)。使用这些函数始终执行 DNS 查询,绕过其他名称解析设施。
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()
设置用于解析器的服务器
不会影响其他解析器:
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.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])
#
创建一个新的解析器。
resolver.cancel()
#
取消此解析器发出的所有未完成的 DNS 查询。相应的回调将被调用,并出现错误,代码为ECANCELLED
。
resolver.setLocalAddress([ipv4][, ipv6])
#
解析器实例将从指定的 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',
]
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
<函数>
将主机名(例如'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}]
如果此方法作为其util.promisify()
ed 版本调用,并且all
未设置为true
,则它会返回Promise
Object
具有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)
#
使用操作系统的底层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
});
如果此方法作为其util.promisify()
ed 版本调用,它将返回一个
Promise
,其中包含hostname
和service
特性。
dns.resolve(hostname[, rrtype], callback)
#
使用 DNS 协议将主机名(例如'nodejs.org'
)解析为资源记录数组。callback
函数具有参数
(err, records)
。成功后,records
将是一个资源记录数组。各个结果的类型和结构根据rrtype
有所不同:
rrtype | records 包含 | 结果类型 | 速记法 |
---|---|---|---|
'A' | IPv4 地址(默认) | <字符串> | dns.resolve4() |
'AAAA' | IPv6 地址 | <字符串> | dns.resolve6() |
'ANY' | 任何记录 | <对象> | dns.resolveAny() |
'CAA' | CA授权记录 | <对象> | dns.resolveCaa() |
'CNAME' | 规范名称记录 | <字符串> | dns.resolveCname() |
'MX' | 邮件交换记录 | <对象> | dns.resolveMx() |
'NAPTR' | 名称权限指针记录 | <对象> | dns.resolveNaptr() |
'NS' | 名称服务器记录 | <字符串> | dns.resolveNs() |
'PTR' | 指针记录 | <字符串> | dns.resolvePtr() |
'SOA' | 规范记录的开始 | <对象> | dns.resolveSoa() |
'SRV' | 服务记录 | <对象> | dns.resolveSrv() |
'TXT' | 文字记录 | <字符串[]> | dns.resolveTxt() |
dns.resolve4(hostname[, options], callback)
#
hostname
<string>要解析的主机名。options
<对象>ttl
<boolean>检索每条记录的生存时间值 (TTL)。当true
时,回调接收{ address: '1.2.3.4', ttl: 60 }
对象数组 而不是字符串数组,TTL 以秒为单位。
callback
<函数>
使用 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
<函数>
使用 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() |
'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 协议解析hostname
的CNAME
记录。传递
给callback
函数的addresses
参数将包含可用于hostname
的规范名称记录数组
(例如['bar.example.com']
)。
dns.resolveCaa(hostname, callback)
#
使用 DNS 协议解析hostname
的CAA
记录。传递
给callback
函数的addresses
参数将包含可用于hostname
的证书颁发机构授权记录数组(例如[{critical: 0, iodef: 'mailto:[email protected]'}, {critical: 128, issue: 'pki.example.com'}]
)。
dns.resolveMx(hostname, callback)
#
使用 DNS 协议解析 hostname
的邮件交换记录(MX
记录)
。传递给callback
函数的addresses
参数将包含一个对象数组,其中包含priority
和exchange
属性(例如[{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.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 地址解析为主机名数组。
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',
]);
如果提供无效地址,将会抛出错误。
当 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');
})();
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',
]
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}]
});
dnsPromises.lookupService(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
});
dnsPromises.resolve(hostname[, rrtype])
#
使用 DNS 协议将主机名(例如'nodejs.org'
)解析为资源记录数组。成功后,将使用资源记录数组解析Promise
。各个结果的类型和结构根据rrtype
有所不同:
rrtype | records 包含 | 结果类型 | 速记法 |
---|---|---|---|
'A' | IPv4 地址(默认) | <字符串> | dnsPromises.resolve4() |
'AAAA' | IPv6 地址 | <字符串> | dnsPromises.resolve6() |
'ANY' | 任何记录 | <对象> | dnsPromises.resolveAny() |
'CAA' | CA授权记录 | <对象> | dnsPromises.resolveCaa() |
'CNAME' | 规范名称记录 | <字符串> | dnsPromises.resolveCname() |
'MX' | 邮件交换记录 | <对象> | dnsPromises.resolveMx() |
'NAPTR' | 名称权限指针记录 | <对象> | dnsPromises.resolveNaptr() |
'NS' | 名称服务器记录 | <字符串> | dnsPromises.resolveNs() |
'PTR' | 指针记录 | <字符串> | dnsPromises.resolvePtr() |
'SOA' | 规范记录的开始 | <对象> | dnsPromises.resolveSoa() |
'SRV' | 服务记录 | <对象> | dnsPromises.resolveSrv() |
'TXT' | 文字记录 | <字符串[]> | dnsPromises.resolveTxt() |
出错时,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
,对象上将出现其他属性:
类型 | 特性 |
---|---|
'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
<字符串>
使用 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
}
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
}
dnsPromises.resolveSrv(hostname)
#
hostname
<字符串>
使用 DNS 协议解析 hostname
的服务记录( SRV
记录)
。成功后,将使用具有以下属性的对象数组解析Promise
:
priority
weight
port
name
{
priority: 10,
weight: 5,
port: 21223,
name: 'service.example.com'
}
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',
]);
如果提供无效地址,将会抛出错误。
当 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
中的配置。