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


  • hostname <string>
  • options <integer> | <Object>

    • family <integer> The record family. Must be 4 or 6. IPv4 and IPv6 addresses are both returned by default.
    • 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. 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.

解析hostname(例如:'nodejs.org')为第一个找到的A(IPv4)或AAAA(IPv6)记录。options可以是对象或者整数。如果options没有被提供,那么IPv4 和 IPv6都是有效的。如果options是整数,只能是46

另外,options可以是一个含有以下属性的对象:

  • family <number> - T地址族。如果提供,必须为整数4或6。如果没有提供,只接受IPv4和IPv6地址。
  • hints: <number> - 如果提供,它必须是一个或多个支持的getaddrinfo标识。如果没有提供,那么没有标识被传递给getaddrinfo。多个标识可以通过在逻辑上ORing它们的值,来传递给hints。支持的getaddrinfo标识请参阅下文。有关支持的标志的更多信息请查询supported getaddrinfo flags章节。
  • all: <boolean> - 值为true时, 回调函数返回一个包含所有解析后地址的数组,否则只返回一个地址。默认值为false

所有的参数都是可选的。

回调函数包含(err, address, family)参数。address是IPv4或IPv6地址字符串。family、是整数4或6,表示地址族(不一定是最初传递给查找的值)。

all属性被设置为true时,回调函数参数变为(err, addresses)addresses则变成一个由addressfamily 属性组成的对象数组。

发生错误时,err是一个Error对象,err.code是错误码。不仅在主机名不存在时,在如没有可用的文件描述符等情况下查找失败,err.code也会被设置为'ENOENT'

dns.lookup() 不需要与DNS协议有任何关系。它仅仅是一个连接名字和地址的操作系统功能。在任何的node.js程序中,它的实现对表现有一些微妙但是重要的影响。在使用dns.lookup()之前请花些时间查询Implementation considerations section章节。

使用例子:

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

// 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.

  • hostname <string>
  • options <integer> | <Object>

    • family <integer> The record family. Must be 4 or 6. IPv4 and IPv6 addresses are both returned by default.
    • 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. 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.

Resolves a hostname (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 'ENOENT' not only when the hostname 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('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.