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>
  • 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'，不仅当主机名不存在时，而且当查找以其他方式失败时，例如没有可用的文件描述符。

dns.lookup() 不一定与域名系统协议有任何关系。 该实现使用一种操作系统工具，可以将名称与地址关联起来，反之亦然。 这种实现会对任何 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

// 当 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。

• 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 callback returns all resolved addresses in an array. Otherwise, returns a single address. Default: false.
  • verbatim <boolean> When true, the callback receives 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. Default value is configurable using dns.setDefaultResultOrder() or --dns-result-order. New code should use { verbatim: true }.
• callback <Function>
  • err <Error>
  • address <string> A string representation of an IPv4 or IPv6 address.
  • family <integer> 4 or 6, denoting the family of address, or 0 if the address is not an IPv4 or IPv6 address. 0 is a likely indicator of a bug in the name resolution service used by the operating system.

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 arguments for callback change to (err, addresses), with addresses being an array of objects with the properties address and family.

On error, err is 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.

dns.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 dns.lookup().

Example usage:

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

If this method is invoked as its util.promisify()ed version, and all is not set to true, it returns a Promise for an Object with address and family properties.