Node.jsでDNS解決順序を操作！dnsPromises.setDefaultResultOrderの具体例
2025-05-27
dnsPromises.setDefaultResultOrder()とは何か？
dnsPromises.setDefaultResultOrder()は、Node.jsのdnsモジュールがホスト名（例: example.com）をIPアドレスに解決する際に、IPv4アドレスとIPv6アドレスのどちらを優先して返すか、または返す順序をどうするかをグローバルに設定するための関数です。
これは主に、dns.lookup()やdnsPromises.lookup()といった関数がIPアドレスを解決する際のデフォルトの挙動を制御するために使われます。
設定できる値
setDefaultResultOrder()には、以下のいずれかの文字列を引数として渡すことができます。
'verbatim': アドレスの順序を変更せず、DNSリゾルバから受け取った通りの順序で返されるように設定します。これがデフォルトの挙動です。'ipv6first': ホスト名を解決した際に、IPv6アドレスがIPv4アドレスよりも優先して返されるように設定します。結果の配列の先頭にIPv6アドレスが来ることが期待されます。'ipv4first': ホスト名を解決した際に、IPv4アドレスがIPv6アドレスよりも優先して返されるように設定します。つまり、結果の配列の先頭にIPv4アドレスが来ることが期待されます。
なぜこれが重要なのか？
サーバーが複数のIPアドレス（IPv4とIPv6）を持っている場合、クライアントがどちらのIPアドレスを使って接続を試みるかは重要な要素になります。
- 特定の要件: アプリケーションの設計上、特定のIPバージョンでの接続を優先する必要がある場合に利用します。
- パフォーマンス: 特定のネットワーク環境では、IPv4またはIPv6のどちらかの方がより高速に接続できる場合があります。この設定によって、アプリケーションのネットワークパフォーマンスを最適化できる可能性があります。
- 互換性: 古いネットワーク環境や、IPv6が完全にサポートされていない環境では、IPv4を優先することで接続の問題を避けることができます。
使用例
const dnsPromises = require('dns').promises;
// IPv4アドレスを優先するように設定
dnsPromises.setDefaultResultOrder('ipv4first');
// ホスト名を解決してみる（この設定が影響します）
dnsPromises.lookup('example.com')
.then(result => {
console.log('IPv4優先の結果:', result);
// result.address は IPv4アドレスであることが期待される
})
.catch(err => {
console.error('解決エラー:', err);
});
// IPv6アドレスを優先するように設定
dnsPromises.setDefaultResultOrder('ipv6first');
dnsPromises.lookup('example.com')
.then(result => {
console.log('IPv6優先の結果:', result);
// result.address は IPv6アドレスであることが期待される
})
.catch(err => {
console.error('解決エラー:', err);
});
// デフォルト（verbatim）に戻す
dnsPromises.setDefaultResultOrder('verbatim');
dnsPromises.lookup('example.com')
.then(result => {
console.log('verbatimの結果:', result);
// 順序は不定（DNSリゾルバの挙動に依存）
})
.catch(err => {
console.error('解決エラー:', err);
});
- Worker Threadsを使用している場合、メインスレッドでの
setDefaultResultOrder()の設定はWorkerに影響しません。Workerスレッド内で個別に設定する必要があります。 - コマンドライン引数
--dns-result-orderでも同じ設定が可能ですが、dnsPromises.setDefaultResultOrder()の方が優先されます。 - この設定は、プロセス全体に影響します。一度設定すると、そのNode.jsプロセス内のすべての
dns.lookup()やdnsPromises.lookup()の挙動に適用されます。
TypeError: The "order" argument must be one of "ipv4first", "ipv6first", or "verbatim".
原因
setDefaultResultOrder()に、許可されていない文字列（例: 'invalid'や'default'など）を引数として渡した場合に発生します。
トラブルシューティング
引数には必ず以下のいずれかの文字列を使用してください。
'verbatim''ipv6first''ipv4first'
<!-- end list -->
// 誤った例
// dnsPromises.setDefaultResultOrder('default'); // TypeErrorが発生
// 正しい例
const dnsPromises = require('dns').promises;
dnsPromises.setDefaultResultOrder('ipv4first');
設定しても期待通りのIPアドレスが返ってこない
原因
これはエラーメッセージとして直接表示されるものではありませんが、setDefaultResultOrder()を設定したにも関わらず、dnsPromises.lookup()などが期待するIPアドレスの順序で結果を返さない場合に起こります。考えられる原因はいくつかあります。
- dns.lookup()のoptions.orderが優先されている
dnsPromises.lookup()(またはdns.lookup()) のオプションにorderプロパティが明示的に指定されている場合、setDefaultResultOrder()で設定されたグローバルな順序よりも、個別のlookup呼び出しのoptions.orderが優先されます。 - ホスト名にIPv4とIPv6アドレスが両方登録されていない
解決しようとしているホスト名に、そもそもIPv4アドレスしか、あるいはIPv6アドレスしか登録されていない場合、どちらを優先しても結果は変わりません。 - ネットワーク環境の影響
特定のネットワーク環境（例: VPN、会社のネットワークポリシー、特定のルーター設定）によっては、DNSリゾルバが特定の順序でしかIPアドレスを返さない場合があります。この場合、Node.js側で順序を強制しようとしても、元のリゾルバの挙動が優先されることがあります。 - DNSキャッシュの影響
Node.js自体、またはOSレベルでDNSキャッシュが効いている場合、設定変更がすぐに反映されないことがあります。
トラブルシューティング
- lookupオプションの確認
dnsPromises.lookup()を呼び出している箇所で、明示的にorderオプションを設定していないか確認します。もし設定している場合は、その設定がグローバルな設定よりも優先されることを理解してください。 <!-- end list -->
// グローバル設定がipv4firstでも、ここではipv6firstが優先される dnsPromises.lookup('example.com', { order: 'ipv6first' }) .then(result => console.log(result)); - ホスト名の確認
digやnslookupコマンドを使って、対象のホスト名が実際にIPv4とIPv6の両方のアドレスを持っているかを確認します。dig example.com AAAA # IPv6アドレスの確認 dig example.com A # IPv4アドレスの確認
- ネットワーク環境の確認
- 別のネットワーク環境（例: 自宅のWi-Fi、スマートフォンのテザリング）で試してみて、問題が解決するかどうかを確認します。
- ネットワーク管理者に、DNS解決のポリシーについて問い合わせてみてください。
- DNSキャッシュのクリア
- Node.jsプロセスを再起動する。
- OSのDNSキャッシュをクリアする（macOS:
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder、Windows:ipconfig /flushdns）。
他のDNS解決方法との混同
原因
Node.jsのdnsモジュールには、dns.lookup()の他にdns.resolve()やdns.resolve4()、dns.resolve6()などの関数があります。setDefaultResultOrder()は**dns.lookup()（およびそのPromise版dnsPromises.lookup()）の挙動にのみ影響を与えます。** dns.resolve*()系の関数は、DNSサーバーから直接レコードを取得するため、setDefaultResultOrder()の影響を受けません。
トラブルシューティング
期待するDNS解決の挙動に応じて、適切な関数を使用しているか確認してください。
- dns.resolve()系
特定のDNSレコード（A, AAAA, MXなど）を直接DNSサーバーに問い合わせて取得します。OSや/etc/hostsの影響を受けず、setDefaultResultOrder()の影響も受けません。 - dns.lookup()
ホスト名をIPアドレスに解決する際に、OSのDNSリゾルバや/etc/hostsなどの設定を考慮して最適なIPアドレスを返すことを目的とします。setDefaultResultOrder()はこれに影響します。
原因
DNS解決は、OSの設定、ネットワーク機器（ルーター、ファイアウォール）、ISPのDNSサーバー、アプリケーションのキャッシュなど、多岐にわたる要素が絡み合って行われます。そのため、どこで問題が発生しているのか特定するのが難しい場合があります。
- パケットキャプチャ
Wiresharkなどのツールを使って、ネットワーク上のDNSクエリとレスポンスをキャプチャすることで、実際にDNSサーバーとの間でどのような通信が行われているかを確認できます。 - 最小限の再現コード
問題が発生するコードの中から、dnsPromises.setDefaultResultOrder()とdnsPromises.lookup()に関連する部分だけを抜き出し、最小限の再現コードを作成します。これにより、問題の切り分けが容易になります。 - NODE_DEBUG=dns 環境変数
Node.jsの内部的なDNS解決のデバッグ情報を出力させることができます。これにより、DNSリクエストがどのように行われているか、どのような結果が返ってきているかを詳しく確認できます。NODE_DEBUG=dns node your_app.js
dnsPromises.setDefaultResultOrder() は、dns.promises モジュールを通じて提供され、ホスト名解決のデフォルトの順序をグローバルに設定するために使用します。この設定は、主に dnsPromises.lookup() メソッドの挙動に影響を与えます。
準備: dns.promises モジュールのインポート
まず、dns.promises をインポートします。
const dnsPromises = require('dns').promises;
例1: IPv4アドレスを優先して解決する (ipv4first)
この例では、'ipv4first' を設定することで、dnsPromises.lookup() が可能な限りIPv4アドレスを優先して返すようにします。
const dnsPromises = require('dns').promises;
async function lookupWithIPv4First() {
console.log('--- IPv4優先設定の例 ---');
// グローバルにIPv4アドレスを優先するよう設定
dnsPromises.setDefaultResultOrder('ipv4first');
console.log('setDefaultResultOrder: ipv4first に設定しました。');
const hostname = 'google.com'; // IPv4とIPv6の両方を持つ可能性が高いホスト名
try {
const result = await dnsPromises.lookup(hostname);
console.log(`'${hostname}' の解決結果 (IPv4優先):`);
console.log(' アドレス:', result.address);
console.log(' ファミリー:', result.family === 4 ? 'IPv4' : 'IPv6');
console.log(' 全結果 (lookupAll=true で確認):');
const allResults = await dnsPromises.lookup(hostname, { all: true });
allResults.forEach(res => {
console.log(` ${res.address} (${res.family === 4 ? 'IPv4' : 'IPv6'})`);
});
} catch (err) {
console.error(`'${hostname}' の解決エラー:`, err.message);
} finally {
// 他のコードに影響を与えないよう、デフォルトに戻すことも検討
// dnsPromises.setDefaultResultOrder('verbatim');
}
console.log('--- 例1 終了 ---\n');
}
lookupWithIPv4First();
実行結果の例
（環境によって結果は異なりますが、address がIPv4になる可能性が高まります）
--- IPv4優先設定の例 ---
setDefaultResultOrder: ipv4first に設定しました。
'google.com' の解決結果 (IPv4優先):
アドレス: 142.250.199.110
ファミリー: IPv4
全結果 (lookupAll=true で確認):
142.250.199.110 (IPv4)
2404:6800:4004:81a::200e (IPv6)
--- 例1 終了 ---
const dnsPromises = require('dns').promises;
async function lookupWithIPv6First() {
console.log('--- IPv6優先設定の例 ---');
// グローバルにIPv6アドレスを優先するよう設定
dnsPromises.setDefaultResultOrder('ipv6first');
console.log('setDefaultResultOrder: ipv6first に設定しました。');
const hostname = 'google.com';
try {
const result = await dnsPromises.lookup(hostname);
console.log(`'${hostname}' の解決結果 (IPv6優先):`);
console.log(' アドレス:', result.address);
console.log(' ファミリー:', result.family === 4 ? 'IPv4' : 'IPv6');
console.log(' 全結果 (lookupAll=true で確認):');
const allResults = await dnsPromises.lookup(hostname, { all: true });
allResults.forEach(res => {
console.log(` ${res.address} (${res.family === 4 ? 'IPv4' : 'IPv6'})`);
});
} catch (err) {
console.error(`'${hostname}' の解決エラー:`, err.message);
} finally {
// 他のコードに影響を与えないよう、デフォルトに戻す
dnsPromises.setDefaultResultOrder('verbatim');
}
console.log('--- 例2 終了 ---\n');
}
lookupWithIPv6First();
実行結果の例
（環境によって結果は異なりますが、address がIPv6になる可能性が高まります）
--- IPv6優先設定の例 ---
setDefaultResultOrder: ipv6first に設定しました。
'google.com' の解決結果 (IPv6優先):
アドレス: 2404:6800:4004:81a::200e
ファミリー: IPv6
全結果 (lookupAll=true で確認):
2404:6800:4004:81a::200e (IPv6)
142.250.199.110 (IPv4)
--- 例2 終了 ---
例3: デフォルトの順序 (verbatim) と個別のlookupオプションとの関係
'verbatim' は、DNSリゾルバから受け取った通りの順序を維持することを意味します。また、dnsPromises.lookup() の options.order を個別に設定すると、グローバルな setDefaultResultOrder() の設定よりも優先されます。
const dnsPromises = require('dns').promises;
async function lookupWithVerbatimAndOptions() {
console.log('--- verbatim と lookup オプションの例 ---');
// グローバルをデフォルトの順序に戻す
dnsPromises.setDefaultResultOrder('verbatim');
console.log('setDefaultResultOrder: verbatim に設定しました。');
const hostname = 'example.com'; // IPv4とIPv6の両方を持つ可能性が高い
// 1. verbatim 設定でのlookup
try {
console.log(`'${hostname}' の解決結果 (verbatim):`);
const result = await dnsPromises.lookup(hostname);
console.log(` デフォルト順序の優先アドレス: ${result.address} (${result.family === 4 ? 'IPv4' : 'IPv6'})`);
const allResults = await dnsPromises.lookup(hostname, { all: true });
allResults.forEach(res => {
console.log(` ${res.address} (${res.family === 4 ? 'IPv4' : 'IPv6'})`);
});
} catch (err) {
console.error(`'${hostname}' の解決エラー (verbatim):`, err.message);
}
console.log('\n--- lookup オプションがグローバル設定を上書きする例 ---');
// 2. グローバルがverbatimでも、lookupオプションでIPv6を強制する
try {
console.log(`'${hostname}' の解決結果 (lookup オプションで IPv6優先):`);
const result = await dnsPromises.lookup(hostname, { order: 'ipv6first' });
console.log(` 強制された優先アドレス: ${result.address} (${result.family === 4 ? 'IPv4' : 'IPv6'})`);
const allResults = await dnsPromises.lookup(hostname, { all: true });
allResults.forEach(res => {
console.log(` ${res.address} (${res.family === 4 ? 'IPv4' : 'IPv6'})`);
});
} catch (err) {
console.error(`'${hostname}' の解決エラー (lookup オプション):`, err.message);
}
console.log('--- 例3 終了 ---\n');
}
lookupWithVerbatimAndOptions();
実行結果の例
（verbatimの順序は環境に依存します。lookupオプションでIPv6を強制した場合はIPv6が先頭に来るはずです。）
--- verbatim と lookup オプションの例 ---
setDefaultResultOrder: verbatim に設定しました。
'example.com' の解決結果 (verbatim):
デフォルト順序の優先アドレス: 93.184.216.34 (IPv4) <- これは環境によってIPv6になる場合もある
93.184.216.34 (IPv4)
2606:2800:220:1:248:1893:25c8:1946 (IPv6)
--- lookup オプションがグローバル設定を上書きする例 ---
'example.com' の解決結果 (lookup オプションで IPv6優先):
強制された優先アドレス: 2606:2800:220:1:248:1893:25c8:1946 (IPv6)
2606:2800:220:1:248:1893:25c8:1946 (IPv6)
93.184.216.34 (IPv4)
--- 例3 終了 ---
例4: エラーハンドリングの例
無効な引数を渡した場合の TypeError を示します。
const dnsPromises = require('dns').promises;
function demonstrateError() {
console.log('--- エラーハンドリングの例 ---');
try {
// 無効な引数を渡す
dnsPromises.setDefaultResultOrder('invalid_order');
console.log('この行は実行されません。');
} catch (err) {
if (err instanceof TypeError) {
console.error('TypeError が発生しました:', err.message);
console.error('正しい引数は "ipv4first", "ipv6first", "verbatim" です。');
} else {
console.error('予期せぬエラー:', err);
}
}
console.log('--- 例4 終了 ---\n');
}
demonstrateError();
--- エラーハンドリングの例 ---
TypeError が発生しました: The "order" argument must be one of "ipv4first", "ipv6first", or "verbatim". Received "invalid_order"
正しい引数は "ipv4first", "ipv6first", "verbatim" です。
--- 例4 終了 ---
dnsPromises.lookup()のoptions.orderを使う
最も直接的な代替手段は、dnsPromises.lookup()（またはコールバック形式のdns.lookup()）を呼び出す際に、個別のオプションとしてorderプロパティを指定することです。
利点
- 柔軟性
アプリケーション内で異なるDNS解決の順序が必要な場合に便利です。 - 粒度の制御
グローバルな設定に依存せず、特定のDNS解決呼び出しのみに適用されるため、より細かく制御できます。
欠点
- 見落としのリスク
新しいlookup呼び出しを追加する際に、このオプションの指定を忘れる可能性があります。 - コードの冗長性
アプリケーション全体で特定の順序を強制したい場合、すべてのlookup呼び出しにoptions.orderを追加する必要があり、コードが冗長になる可能性があります。
コード例
const dnsPromises = require('dns').promises;
async function lookupSpecificOrder() {
console.log('--- 個別 lookup オプションの例 ---');
// グローバル設定は任意（ここではデフォルトのままか、別で設定されていても問題なし）
// dnsPromises.setDefaultResultOrder('verbatim');
const hostname = 'example.com';
// IPv4アドレスを優先して解決
try {
const resultIPv4 = await dnsPromises.lookup(hostname, { order: 'ipv4first' });
console.log(`'${hostname}' の解決結果 (個別IPv4優先):`);
console.log(` アドレス: ${resultIPv4.address}, ファミリー: ${resultIPv4.family}`);
} catch (err) {
console.error(`'${hostname}' の解決エラー (個別IPv4優先):`, err.message);
}
// IPv6アドレスを優先して解決
try {
const resultIPv6 = await dnsPromises.lookup(hostname, { order: 'ipv6first' });
console.log(`'${hostname}' の解決結果 (個別IPv6優先):`);
console.log(` アドレス: ${resultIPv6.address}, ファミリー: ${resultIPv6.family}`);
} catch (err) {
console.error(`'${hostname}' の解決エラー (個別IPv6優先):`, err.message);
}
console.log('--- 例 終了 ---\n');
}
lookupSpecificOrder();
dnsPromises.lookup()のoptions.familyを使う
dnsPromises.lookup()のoptions.familyプロパティを使って、IPv4 (4) または IPv6 (6) のどちらか一方のアドレスのみを解決するように強制することもできます。
利点
- シンプルさ
目的が明確な場合にコードがシンプルになります。 - 確実性
特定のIPバージョンのみが必要な場合、最も確実な方法です。
欠点
- 解決失敗のリスク
指定したファミリーのアドレスが見つからない場合、解決に失敗します。 - 柔軟性の欠如
アプリケーションが両方のIPバージョンに対応している必要がある場合、またはフォールバックが必要な場合には適しません。
コード例
const dnsPromises = require('dns').promises;
async function lookupSpecificFamily() {
console.log('--- 特定ファミリー指定の例 ---');
const hostname = 'example.com';
// IPv4アドレスのみを解決
try {
const resultIPv4Only = await dnsPromises.lookup(hostname, { family: 4 });
console.log(`'${hostname}' の解決結果 (IPv4のみ):`);
console.log(` アドレス: ${resultIPv4Only.address}, ファミリー: ${resultIPv4Only.family}`);
} catch (err) {
console.error(`'${hostname}' の解決エラー (IPv4のみ):`, err.message);
}
// IPv6アドレスのみを解決
try {
const resultIPv6Only = await dnsPromises.lookup(hostname, { family: 6 });
console.log(`'${hostname}' の解決結果 (IPv6のみ):`);
console.log(` アドレス: ${resultIPv6Only.address}, ファミリー: ${resultIPv6Only.family}`);
} catch (err) {
console.error(`'${hostname}' の解決エラー (IPv6のみ):`, err.message);
}
console.log('--- 例 終了 ---\n');
}
lookupSpecificFamily();
コマンドライン引数 --dns-result-order を使う
Node.jsの起動時に、--dns-result-order コマンドライン引数を使用して、グローバルなDNS解決の順序を設定できます。これはdnsPromises.setDefaultResultOrder() と同じ効果を持ちますが、プログラム内で設定するのではなく、起動時に指定します。
利点
- デプロイ環境での制御
DockerコンテナやKubernetesなどのデプロイ環境で、環境変数や起動スクリプトを通じて簡単に設定できます。 - コードの変更不要
アプリケーションコードを変更することなく、DNS解決の順序を変更できます。
欠点
- 優先順位
dnsPromises.setDefaultResultOrder()がプログラム内で呼び出された場合、このコマンドライン引数よりもプログラム内の設定が優先されます。 - プログラムからの動的な変更不可
アプリケーションの実行中に動的にDNS解決の順序を変更することはできません。
使用方法
# IPv4を優先してNode.jsアプリケーションを実行
node --dns-result-order=ipv4first your_app.js
# IPv6を優先してNode.jsアプリケーションを実行
node --dns-result-order=ipv6first your_app.js
# デフォルト（verbatim）でNode.jsアプリケーションを実行
node --dns-result-order=verbatim your_app.js
カスタムのDNSリゾルバを実装する（高度な方法）
Node.jsのhttp.Agentなどのネットワークモジュールは、カスタムのlookup関数を渡すことをサポートしています。これにより、DNS解決のロジックを完全に制御できます。これは、DNSキャッシュを独自に実装したり、特定のDNSサーバーに問い合わせたり、複雑なルーティングロジックを適用したりする場合に有効です。
利点
- 高度な機能
キャッシュ、フォールバック、特定のサーバーへの問い合わせなど、高度なDNS機能を実現できます。 - 究極の制御
DNS解決のあらゆる側面を完全に制御できます。
欠点
- Node.jsの内部挙動への依存
Node.jsの内部的なDNS解決メカニズム（getaddrinfoなど）に依存しているため、理解が深くないと予期せぬ問題を引き起こす可能性があります。 - オーバーヘッド
適切に実装しないと、パフォーマンスに悪影響を与える可能性があります。 - 複雑性
実装が非常に複雑になり、デバッグも困難になる可能性があります。
const http = require('http');
const dnsPromises = require('dns').promises;
// カスタムのlookup関数
async function customLookup(hostname, options, callback) {
console.log(`カスタム lookup が呼び出されました: ${hostname}`);
try {
// ここで独自のロジックを実装
// 例: IPv6を優先し、見つからなければIPv4にフォールバックする
let result;
try {
// まずIPv6を試す
result = await dnsPromises.lookup(hostname, { family: 6, all: true });
} catch (e) {
// IPv6が見つからなければIPv4を試す
console.log(`IPv6が見つかりません。IPv4を試します: ${hostname}`);
result = await dnsPromises.lookup(hostname, { family: 4, all: true });
}
// 取得したアドレスを独自の順序で返す
// ここでは単純に最初のアドレスを返す
if (result.length > 0) {
callback(null, result[0].address, result[0].family);
} else {
callback(new Error('No address found'), null, null);
}
} catch (err) {
callback(err, null, null);
}
}
// HTTPリクエストでカスタムlookupを使う例
const agent = new http.Agent({ lookup: customLookup });
http.get({
hostname: 'example.com',
agent: agent // カスタムAgentを使用
}, (res) => {
console.log(`HTTPステータス: ${res.statusCode}`);
res.on('data', () => {});
res.on('end', () => console.log('HTTPリクエスト完了'));
}).on('error', (e) => {
console.error(`HTTPリクエストエラー: ${e.message}`);
});
-
Node.jsの標準機能では実現できない高度なDNS解決ロジックが必要な場合
- カスタムの
lookup関数を実装することを検討します。
- カスタムの
-
特定のIPバージョンのみが必要な場合
dnsPromises.lookup()のoptions.familyを使うのが最も確実です。
-
特定のlookup呼び出しのみで順序を制御したい場合
dnsPromises.lookup()のoptions.orderを使うのが最適です。
-
アプリケーション全体で特定のDNS順序を強制したい場合
- 最も簡単なのは
dnsPromises.setDefaultResultOrder()です。 - デプロイ時に設定を変更したい場合は
--dns-result-orderコマンドライン引数が適しています。
- 最も簡単なのは