Node.js v25.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[]>

RFC 5952 に従ってフォーマットされた、現在 DNS 解決用に設定されている IP アドレス文字列の配列を返します。カスタムポートが使用されている場合、文字列にはポートセクションが含まれます。

[
  '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 } (下記参照) と共に使用される場合、システムの DNS リゾルバに応じて、IPv4 と IPv6 アドレスの一方または両方が返されます。デフォルト: 0。
  • hints <number> 1つ以上のサポートされている getaddrinfo フラグ。複数のフラグは、それらの値をビット単位の OR で渡すことができます。
  • all <boolean> true の場合、コールバックは解決されたすべてのアドレスを配列で返します。それ以外の場合は、単一のアドレスを返します。デフォルト: false。
  • order <string> verbatim の場合、解決されたアドレスはソートされずに返されます。ipv4first の場合、解決されたアドレスは IPv4 アドレスが IPv6 アドレスの前に配置されるようにソートされます。ipv6first の場合、解決されたアドレスは IPv6 アドレスが IPv4 アドレスの前に配置されるようにソートされます。デフォルト: verbatim (アドレスは並べ替えられません)。デフォルト値は dns.setDefaultResultOrder() または --dns-result-order を使用して設定可能です。
  • verbatim <boolean> true の場合、コールバックは DNS リゾルバが返した順序で IPv4 と IPv6 アドレスを受け取ります。false の場合、IPv4 アドレスは IPv6 アドレスの前に配置されます。このオプションは order に置き換えられるため非推奨です。両方が指定された場合、order が優先されます。新しいコードでは order のみを使用すべきです。デフォルト: true (アドレスは並べ替えられません)。デフォルト値は dns.setDefaultResultOrder() または --dns-result-order を使用して設定可能です。
• callback <Function>
  • `err` <Error>
  • address <string> IPv4 または IPv6 アドレスの文字列表現。
  • family <integer> address のファミリーを示す 4 または 6。アドレスが 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() は必ずしも 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

指定された address と port を、オペレーティングシステムの基盤となる getnameinfo 実装を使用してホスト名とサービスに解決します。

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> 各レコードの Time-To-Live (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> 各レコードの Time-To-Live (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 で利用可能なテキストレコードの2次元配列です (例: [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ])。各サブ配列には、1つのレコードの TXT チャンクが含まれます。ユースケースによっては、これらを結合するか、別々に扱うことができます。

dns.reverse(ip, callback)#

• ip <string>
• callback <Function>
  • `err` <Error>
  • hostnames <string[]>

IPv4 または IPv6 アドレスをホスト名の配列に解決する逆引き DNS クエリを実行します。

エラーが発生した場合、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 よりも優先度が高いです。ワーカースレッド を使用する場合、メインスレッドからの dns.setDefaultResultOrder() はワーカーのデフォルトの dns 順序に影響しません。

dns.getDefaultResultOrder()#

dns.lookup() と dnsPromises.lookup() における order のデフォルト値を取得します。値は以下の通りです。

• ipv4first: order のデフォルトが ipv4first の場合。
• ipv6first: order のデフォルトが ipv6first の場合。
• verbatim: order のデフォルトが verbatim の場合。

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.setServers() メソッドは、DNS クエリが進行中に呼び出してはいけません。

dns.setServers() メソッドは dns.resolve(), dns.resolve*(), dns.reverse() にのみ影響を与え (特に dns.lookup() には影響しません)。

このメソッドは resolve.conf のように動作します。つまり、最初に提供されたサーバーでの解決が NOTFOUND エラーになった場合、resolve() メソッドは後続のサーバーでの解決を試みません。フォールバック DNS サーバーは、前のサーバーがタイムアウトしたり、他のエラーになった場合にのみ使用されます。

DNS promises API#

dns.promises API は、コールバックを使用する代わりに Promise オブジェクトを返す非同期 DNS メソッドの代替セットを提供します。API は require('node:dns').promises または require('node:dns/promises') を介してアクセスできます。

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 プログラムの動作に微妙ながらも重大な影響を与える可能性があります。