Node.js v24.0.0 文档

类：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) => {
  // ...
});copy

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.resolveTlsa()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

dns.getServers()#

• 返回：<string[]>

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

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

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

• hostname <string>
• options <integer> | <Object>
  • family <integer> | <string> 记录族。 必须是 4、6 或 0。 由于向后兼容的原因，'IPv4' 和 'IPv6' 分别被解释为 4 和 6。 值 0 表示返回 IPv4 或 IPv6 地址。 如果将值 0 与 { all: true } 一起使用（请参见下文），则返回一个或两个 IPv4 和 IPv6 地址，具体取决于系统的 DNS 解析器。 默认值： 0。
  • hints <number> 一个或多个支持的 getaddrinfo 标志。 可以通过按位 OR 运算它们的值来传递多个标志。
  • 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> 4 或 6，表示 address 的族，如果地址不是 IPv4 或 IPv6 地址，则为 0。0 可能是操作系统使用的名称解析服务中存在错误的指示。

将主机名（例如 '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'，而且还会在查找因其他方式失败时（例如没有可用的文件描述符）设置为 '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}]copy

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

dns.lookupService(address, port, callback)#

• address <string>
• port <number>
• callback <Function>
  • err <Error>
  • hostname <string> 例如 example.com
  • service <string> 例如 http

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

如果 address 不是有效的 IP 地址，则会抛出 TypeError。 port 将被强制转换为数字。 如果它不是一个合法的端口，则会抛出 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
});copy

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

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

• hostname <string> 要解析的主机名。
• rrtype <string> 资源记录类型。 默认值： 'A'。
• callback <Function>
  • err <Error>
  • records <string[]> | <Object[]> | <Object>

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

发生错误时，err 是一个 Error 对象，其中 err.code 是 DNS 错误代码之一。

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

使用 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>
  • err <Error>
  • addresses <string[]> | <Object[]>

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

dns.resolveAny(hostname, callback)#

• hostname <string>
• callback <Function>
  • err <Error>
  • ret <Object[]>

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

这里是一个传递给回调的 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 } ] copy

DNS服务器运营商可以选择不响应 ANY 查询。 最好调用单独的方法，例如 dns.resolve4()，dns.resolveMx() 等。 更多详细信息，请参见 RFC 8482。

dns.resolveCname(hostname, callback)#

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

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

dns.resolveCaa(hostname, callback)#

• hostname <string>
• callback <Function>
  • err <Error>
  • records <Object[]>

使用 DNS 协议来解析 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[]>

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

dns.resolveNaptr(hostname, callback)#

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

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

dns.resolveNs(hostname, callback)#

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

使用 DNS 协议来解析 hostname 的名称服务器记录（NS 记录）。 传递给 callback 函数的 addresses 参数将包含一个可用于 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 函数的 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
} copy

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'
} copy

dns.resolveTlsa(hostname, callback)#

• hostname <string>
• callback <Function>
  • err <Error>
  • records <Object[]>

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

• certUsage
• selector
• match
• data

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

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.setDefaultResultOrder(order)#

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

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

• ipv4first：将默认 order 设置为 ipv4first。
• ipv6first：将默认 order 设置为 ipv6first。
• verbatim：将默认 order 设置为 verbatim。

默认值为 verbatim，并且 dns.setDefaultResultOrder() 的优先级高于 --dns-result-order。 当使用 worker 线程时，来自主线程的 dns.setDefaultResultOrder() 不会影响 worker 中的默认 dns 顺序。

dns.getDefaultResultOrder()#

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

• ipv4first：对于默认设置为 ipv4first 的 order。
• ipv6first：对于默认设置为 ipv6first 的 order。
• verbatim：对于默认设置为 verbatim 的 order。

dns.setServers(servers)#

• servers <string[]> RFC 5952 格式地址的数组

设置在执行 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',
]); copy

如果提供了无效的地址，将抛出一个错误。

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

dns.setServers() 方法仅影响 dns.resolve()、dns.resolve*() 和 dns.reverse()（并且专门 *不* 影响 dns.lookup()）。

此方法的工作方式与 resolve.conf 非常相似。 也就是说，如果尝试使用提供的第一个服务器进行解析导致 NOTFOUND 错误，则 resolve() 方法将 *不* 尝试使用提供的后续服务器进行解析。 仅当较早的 DNS 服务器超时或导致某些其他错误时，才会使用回退 DNS 服务器。

DNS promises API#

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

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');
})();copy

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

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}]
});copy

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
});copy

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

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

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

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

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

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

错误码#

每个 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 程序的行为产生微妙但重要的影响。