URL エンコーディング:クエリパラメータとパスをパーセントエンコードする

パーセントエンコーディングは安全でない文字を %XX に置き換え、任意のテキストを URL に安全に含められるようにします。どの文字をエスケープし、どう戻すかを把握しましょう。

パーセントエンコーディングとは

URL 内で許可されない文字は、パーセント記号と 2 桁の 16 進数に置き換えられます。スペースは %20、& は %26 になります。

encodeURIComponent と encodeURI

単一のクエリ値やパスセグメントには encodeURIComponent を使ってください —— /, ?, &, = をエスケープしてくれます。encodeURI は URL 全体に対してだけ使い、こうした文字は構造として残します。

+ と %20 の罠

クエリ文字列では、空白は + (フォームエンコーディング)または %20 として現れる可能性があります。decodeURIComponent は + を空白に変換しません。フォームエンコードされたデータを扱う場合は、デコード前に + を置換しておきます。

二重エンコーディング

すでにエンコード済みの文字列をもう一度エンコードすると %20 は %2520 になります。出力に %25 が並んでいたら、その値は 2 回エンコードされています —— 変化しなくなるまで繰り返しデコードしてください。

予約文字と非予約文字

RFC 3986 は URL の文字を予約文字(: / ? # などの gen-delims、& = などの sub-delims)と非予約文字(英数字と - . _ ~)に分けます。非予約文字は決してエンコード不要です。予約文字は値として現れるときだけエンコードが必要で、URL の構造として使われる場合は不要です。

URL 全体のエンコードと単一値のエンコード

encodeURI は URL 全体向け:: / ? # & = をそのまま残し、URL の形を保ちます。encodeURIComponent はパスセグメントやクエリパラメータに入れる単一の値向け:それらの構造文字をエスケープして、値が枠を超えて漏れないようにします。

プログラムで安全にクエリ文字列を組み立てる

文字列連結より、URLSearchParams(ブラウザ)や url.URLSearchParams(Node)を優先してください。どちらも鍵と値を適切にエンコードし、複数値のパラメータも扱え、最もよくあるミス —— & や = を含むパラメータをエンコードし忘れる —— を防いでくれます。