navigator.onLineは嘘をつく。Is-Onlineで実現する確実なネット接続判定

はじめに

「Wi-Fiには繋がっているのに、インターネットには繋がっていない」——そんな経験はありませんか。ブラウザが提供するnavigator.onLineは、実はこの状況を正しく判定できません。あくまでネットワークインターフェースが有効かどうかを見ているだけで、実際にインターネットへ到達できるかどうかまでは保証してくれないのです。

CLIツールやNode.jsのバッチ処理でも同じ問題は起こります。サーバー起動時に「本当に外部と通信できる状態か」を確認したいのに、確実な手段がなく困った経験がある方も多いはずです。

そこで登場するのが今回紹介するis-onlineです。実際に外部サーバーへ疎通確認を行うことで、名前の通り「本当にオンラインかどうか」を判定してくれるシンプルなライブラリです。

Is-Onlineとは

is-onlineは、Sindre Sorhus氏が公開しているインターネット接続確認用のライブラリです。DNSクエリやHTTPS通信など複数の手段を並行して試し、いずれかが成功すればオンラインと判定するという堅実な設計になっています。Node.js 20以上に対応し、Fetch APIを使ったモダンな実装のためブラウザ向けにバンドルすることも可能です。

主な特徴

• 複数チェックの並行実行 - icanhazip.comやipify.orgへのHTTPS取得、OpenDNS・GoogleへのDNSクエリ、AppleのCaptive Portalテストページ、CloudflareのHTTPS確認などを同時に実行し、いずれか一つでも成功すればオンラインと判定します
• 柔軟なタイムアウト・キャンセル制御 - timeoutオプションやAbortSignalに対応しており、応答を待つ時間や処理の中断を細かく制御できます
• フォールバックURLの指定 - すべての標準チェックが失敗した場合に備えて、独自のfallbackUrlsを設定できます

インストール

npm install is-online

pnpmやyarnを使っている場合も同様です。

pnpm add is-online

このパッケージはESMのみの提供となっているため、import構文で利用する点に注意してください。

基本的な使い方

もっともシンプルな使い方は、isOnline()を呼び出すだけです。

import isOnline from 'is-online';

console.log(await isOnline());
//=> true

戻り値は真偽値のPromiseなので、条件分岐にそのまま使えます。

import isOnline from 'is-online';

if (await isOnline()) {
  console.log('インターネットに接続されています');
} else {
  console.log('オフラインです');
}

タイムアウトを指定したい場合は、オプションで秒数（ミリ秒）を渡します。デフォルトは5000msです。

import isOnline from 'is-online';

const online = await isOnline({timeout: 10_000});
console.log(online);

AbortSignalを使えば、他の処理と連動して接続確認を途中でキャンセルすることもできます。中断された場合はfalseが返ります。

import isOnline from 'is-online';

const controller = new AbortController();

setTimeout(() => controller.abort(), 3000);

const online = await isOnline({signal: controller.signal});
console.log(online);

実践的なユースケース

CLIツールの起動時チェック

外部APIを呼び出すCLIツールで、処理を始める前にネット接続を確認しておくと、ユーザーに親切なエラーメッセージを出せます。

import isOnline from 'is-online';

async function main() {
  if (!(await isOnline())) {
    console.error('インターネットに接続されていません。接続を確認してから再実行してください。');
    process.exitCode = 1;
    return;
  }

  console.log('接続を確認しました。処理を開始します。');
  // ここに本来の処理を書く
}

main();

社内ネットワーク向けのフォールバックURL設定

パブリックなDNSサーバーやサイトへの通信が制限された環境（社内ネットワークなど）では、fallbackUrlsで自前の疎通確認先を指定できます。

import isOnline from 'is-online';

const online = await isOnline({
  fallbackUrls: ['https://internal.example.com/health'],
  timeout: 3000,
});

console.log(online ? 'ネットワークは正常です' : 'ネットワークに問題があります');

定期的な接続監視

サーバー常駐プロセスの中で、一定間隔で接続状態を監視し、切断を検知したらログに残すといった使い方もできます。

import isOnline from 'is-online';

setInterval(async () => {
  const online = await isOnline({timeout: 5000});

  if (!online) {
    console.warn(`[${new Date().toISOString()}] 接続断を検知しました`);
  }
}, 60_000);

まとめ

is-onlineは、navigator.onLineだけでは判断できない「本当にインターネットへ到達できているか」を、複数の手段を組み合わせて確実に判定してくれるライブラリです。タイムアウトやキャンセル、フォールバックURLといった実用的なオプションも揃っており、CLIツールからサーバーの常駐プロセスまで幅広い場面で活用できます。

接続確認の実装で悩んでいたら、まずはnpm install is-onlineから試してみてはいかがでしょうか。