JavaScriptのURL.canParse()：URLを解析できるか判定する方法

URLの入力を真偽値でチェックする

プロフィールのリンク欄や、記事管理画面の参照先URLを検証するとき、「この文字列をURLとして扱えるか」を調べたい場面があります。独自の正規表現で判定しようとすると、相対パスやポート番号など、考慮する条件が増えてしまいます。

URL.canParse()は、入力をURLとして解析できる場合にtrue、できない場合にfalseを返す静的メソッドです。URLオブジェクトを先に作る必要はありません。文字列のURL構文を判定する用途では、失敗するたびに例外を捕捉するコードを減らせます。MDNのAPI解説

ただし、判定対象はURLとしての解析可否です。リンク先が存在するか、アクセスしてよいか、アプリケーションが受け付ける種類かは別の条件です。本記事では、この区別を保ちながら入力チェックへ組み込む方法を扱います。

動作環境と対応バージョン

確認日は2026年9月22日です。ブラウザーについて、MDNでは2023年12月以降、主要ブラウザーを横断して利用可能になった機能として扱われています。古いブラウザーや組み込みWebViewまで一律に対応しているとは限りません。実行時にはtypeof URL.canParse === "function"で利用可能か確認します。MDNの互換性情報

Node.jsでも同じAPIを利用できます。公式資料による追加バージョンはv19.9.0およびv18.17.0です。本記事の実行環境にはNode.js 24系を使用できます。追加バージョンの記載は、その古い系列の利用を推奨する意味ではありません。Node.jsのURL API

以下のコードはブラウザーとNode.jsの両方を対象とし、グローバルのURLを利用します。追加パッケージやimportは不要です。DOM、ファイル操作、外部通信にも依存しません。

引数と戻り値を理解する

呼び出し方はURL.canParse(input)またはURL.canParse(input, base)です。

• inputは解析したいURLです。絶対URL、または相対URLを渡します。
• baseは相対URLの解決に使う基準URLです。省略するとundefinedとして扱われます。
• 戻り値は真偽値です。解析できればtrue、できなければfalseになります。

たとえばhttps://example.com/helpは単独で解析できます。一方、/helpには接続先の情報がないため、基準URLが必要です。ブラウザー内で呼んでも、表示中のページのURLが自動で基準になるわけではありません。MDNの引数説明

文字列以外を渡した場合

APIは引数を文字列化します。そのため、引数を受け取れたことと、アプリケーションにとって適切な入力であることは一致しません。フォームやJSON由来の値を扱う関数では、先にtypeof input === "string"を確認すると意図が明確になります。

また、文字列化に独自の処理を持つオブジェクトは、その処理自体が例外を投げる可能性があります。「どんな値でも絶対に例外を投げないAPI」と解釈しないでください。本記事の実用例は入力を文字列に限定します。

コピーして動かす基本例

次のコード全体を実行すると、絶対URL、相対URL、壊れたURLの違いを確認できます。外側のブロックは、ブラウザーのコンソールで繰り返し実行しやすくするために付けています。

{
  if (typeof URL === "undefined" ||
      typeof URL.canParse !== "function") {
    console.log("この環境はURL.canParse()に対応していません");
  } else {
    const cases = [
      ["絶対URL", "https://example.com/docs", undefined],
      ["基準なしの相対URL", "/docs", undefined],
      ["基準ありの相対URL", "/docs", "https://example.com/"],
      ["ホスト名がないURL", "https://", undefined],
      ["空文字と基準URL", "", "https://example.com/docs/"],
      ["メール用URL", "mailto:team@example.com", undefined]
    ];

    for (const [label, input, base] of cases) {
      console.log(`${label}: ${URL.canParse(input, base)}`);
    }
  }
}

ブラウザーで実行する

対応ブラウザーで空のタブを開き、開発者ツールのConsoleを選びます。上のJavaScript全体を入力して実行してください。HTMLファイルやローカルサーバーを用意する必要はありません。

Node.jsで実行する

Node.js 24系を用意し、上のJavaScriptをurl-check.jsという名前で保存します。ターミナルで保存先のフォルダーを開き、次のコマンドを実行します。

node --version
node url-check.js

最初のコマンドでバージョンを確認し、次のコマンドでファイルを実行します。未対応の環境では、サンプルは判定処理へ進まず、未対応というメッセージを表示します。

期待出力

対応環境での期待出力は次のとおりです。これは仕様に基づく期待値であり、本記事の作成時に実機実行した結果ではありません。

絶対URL: true
基準なしの相対URL: false
基準ありの相対URL: true
ホスト名がないURL: false
空文字と基準URL: true
メール用URL: true

空文字でも有効な基準URLがあれば解析できます。入力必須の欄では、空文字を別途拒否する必要があると分かります。また、mailto:もURLなので、Webページ向けのリンク欄で受け付けるかどうかは追加で判断します。

実用例：HTTPSの絶対URLだけを受け付ける

ここでは「参照先にはHTTPSの絶対URLを登録する」という要件を想定します。相対URLを許可しないため、baseを渡しません。解析できることを確認した後、URLのprotocolを調べます。

以下も独立して実行できるコードです。ブラウザーではConsoleへ入力し、Node.jsではhttps-link-check.jsへ保存してnode https-link-check.jsで実行します。

{
  function validateHttpsLink(input) {
    if (typeof URL === "undefined" ||
        typeof URL.canParse !== "function") {
      return "NG: 実行環境が未対応です";
    }

    if (typeof input !== "string") {
      return "NG: 文字列を入力してください";
    }

    const value = input.trim();
    if (value === "") {
      return "NG: URLを入力してください";
    }

    if (!URL.canParse(value)) {
      return "NG: 絶対URLとして解析できません";
    }

    const parsed = new URL(value);
    if (parsed.protocol !== "https:") {
      return "NG: HTTPSのURLを指定してください";
    }

    return `OK: ${parsed.href}`;
  }

  const inputs = [
    "  https://example.com/docs  ",
    "/docs",
    "http://example.com/",
    "mailto:team@example.com",
    "   ",
    null
  ];

  for (const input of inputs) {
    console.log(validateHttpsLink(input));
  }
}

期待出力は次のとおりです。

OK: https://example.com/docs
NG: 絶対URLとして解析できません
NG: HTTPSのURLを指定してください
NG: HTTPSのURLを指定してください
NG: URLを入力してください
NG: 文字列を入力してください

new URL(value)には、直前に解析可能と判定した同じ文字列を渡しています。通常の組み込みAPIを使うこの条件では、URL構文エラーを処理するためのtry...catchは不要です。一般にはnew URL()へ解析不能な値を渡すとTypeErrorになるため、判定と生成で異なる値を使わないようにします。MDNのURLコンストラクター

validateHttpsLink()の戻り値は表示用の文字列です。保存処理へ組み込むときは、成功・失敗とメッセージを別のプロパティで返す設計にすると、表示文言に依存せず分岐できます。

失敗しやすい条件と制約

基準URLを渡すと判定の意味が変わる

たとえばexample.comは、基準URLなしでは絶対URLとして解析できません。しかし基準URLを渡すと、相対パスとして扱える場合があります。「利用者がドメイン名を正しく入力したか」を確認したいのに、無条件でbaseを補うと、想定と違う入力まで通過します。

相対URLを受け付けるかどうかを先に決め、そのルールに合わせて引数を選んでください。基準URL自体も有効な値に固定しておくと、入力の問題と設定の問題を切り分けやすくなります。

解析成功は接続成功を意味しない

URL.canParse()は同期処理です。Promiseを返さず、awaitも不要で、判定のために接続先へ通信しません。そのため、DNSの解決、HTTPステータス、ページの存在は確認しません。

実用例のOKも、HTTPSの絶対URLという条件を満たしたという意味です。接続先の信頼性を保証する表示ではありません。特定のサービスへのリンクだけを許す要件なら、解析後のホスト名などにも条件を設けます。

入力の表記をそのまま保存するとは限らない

URLをオブジェクトにすると、hrefは解析後の表記を返します。入力文字列と完全に一致するとは限りません。元の入力を監査や再編集に使う場合は、元の文字列と解析後の値を区別して保持する設計が適しています。Node.jsのURL API解説

活用事例と導入の進め方

プロフィール欄では絶対URLだけを受け付け、記事管理画面ではサイト内の相対パスも受け付ける、といった使い分けができます。CSVの取り込み処理でも、行ごとのURL構文チェックに利用できます。

導入時は、絶対URLだけにするか、空欄を許すか、どのプロトコルを受け付けるかを決めます。そのうえで、型と空欄を確認し、URL.canParse()で解析可否を調べ、用途固有の条件を追加します。この順序なら、入力を拒否した理由も説明しやすくなります。

公式参考資料

• MDN：URL.canParse()の仕様と引数で、真偽値による判定と文字列化の扱いを確認できます。
• MDN：URL.canParse()のブラウザー互換性で、対象ブラウザーの対応状況を確認できます。
• Node.js：URL.canParse()に、追加バージョンと引数が記載されています。
• MDN：URLコンストラクターで、解析後のオブジェクトと解析失敗時の例外を確認できます。
• Node.js：URL API全体で、ブラウザー互換のURLクラスと各プロパティを確認できます。