URLエンコードとクエリ文字列：実践ガイド

URLのパスとクエリで使用できる文字は限られています。それ以外の文字はすべてパーセントエンコードする必要があります（例：スペース → %20、& → %26）。これを誤ると、404エラー、アナリティクスタグの破損、そして気づきにくいAPIのバグにつながります。

エンコードが必要な文字とは？

• スペース、&、=、#、または非ASCII文字（絵文字、アクセント記号など）を含むクエリの値はエンコードが必要です。
• スラッシュや特殊文字を含むパスセグメントもエンコードが必要です。そうしないと、ルーターがセグメントの区切りを誤って解釈します。

ブラウザはアドレスバーに「見やすい」URLを表示しますが、実際の通信ではエンコードされた形式で送信しています。一方APIでは、文字列を手動で組み立てる際に明示的にエンコードすることが求められます。

encodeURIComponent と encodeURI の違い

JavaScriptでの使い分け：

• encodeURIComponent — クエリパラメータの値（通常はキーも含む）に使用します。URLを壊す可能性のある文字をほぼすべてエンコードします。
• encodeURI — ? や # などの区切り文字を保持する必要がある場合に、URL全体に対して使用します。日常的なAPI開発ではほとんど使いません。

const q = "hello world & friends";
const params = new URLSearchParams({ q });
console.log(params.toString()); // q=hello+world+%26+friends

URLSearchParams は標準的な application/x-www-form-urlencoded 形式のクエリのエンコードを自動で処理するため、手動での文字列結合より推奨されます。

多数のパラメータを含むURLの構築

UTMタグ、フィルター、APIキーを追加していくと、ミスが重なりやすくなります。? の重複、エンコードされていない &、あるいは順序の曖昧さなどが典型的な問題です。小さなヘルパー関数やビジュアルビルダーを使うことで、最終的な文字列を常に有効な状態に保てます。

URL Encode / Decode ツールで文字列がどのように変化するか確認し、URL & Query String Builder でUTF-8セーフなエンコードを使ってリンクを組み立ててみましょう。

cURL と fetch

ブラウザのDevToolsからリクエストをコピーする際は、すでにエンコードされているクエリ文字列に注意してください。コードに貼り付けると、値が二重エンコードされてしまう場合があります。cURL to fetch() コンバーターを使えば、動作確認済みのcURLをJavaScriptに変換しながら、URLを別途検証できます。

リンクが「Chromeでは動くのにスクリプトで失敗する」場合は、生のクエリ文字列をバイト単位で比較してみましょう。

クイックチェックリスト

• ?a=...&b=... に結合する前に値をエンコードする
• 手動での文字列構築より URL + URLSearchParams を優先する
• 国際化ドメイン名（IDN）では、ホスト名のPunycode変換はブラウザが処理するため、エンコードはパスとクエリに集中する