這兩個函式幾乎每個 JavaScript 工程師都用過,但用錯的人也不少。差異只有一句話,理解它卻需要先看 URI 的字符分類。
encodeURI 與 encodeURIComponent 都是 ECMA-262 定義的全域函式,所有遵循該標準的語言(JavaScript、ActionScript 等)都會實作。它們的用途都是把 URI(RFC-2396)中的字符做 escaping 編碼,差別在於哪些字符會被編碼。
保留字符(reserved):用來分隔 URI 各部分的關鍵字符。
; / ? : @ & = + $ ,
Mark 字符:RFC-2396 特別定義但未明確說明用途,可能與其他標準相關。
- _ . ! ~ * ' ( )
基本字符(alphanum):所有大寫字母、小寫字母與數字,是 URI 的主體。
encodeURI:對「非基本字符、非 Mark 字符、非保留字符」的部分做編碼。也就是說,/、?、:、& 這些結構性字符會被保留下來。
encodeURIComponent:連保留字符也一起編碼。例如 : 會變成 %3A,/ 變成 %2F。
編碼規則本身相同:需要轉義的字符依 UTF-8 轉為一組十六進位 %xx。ASCII 可視字符用一個位元組表示;\u0080 到 \u07ff 之間用兩個位元組;其餘 16 位元 Unicode 字符用三個位元組。例如空格 → %20。
var uri = "my test.asp?name=ståle&car=saab"; encodeURI(uri); // my%20test.asp?name=st%C3%A5le&car=saab // ↑ ? 與 & 保留下來了 var uri2 = "https://jb51.net/my test.asp?name=ståle&car=saab"; encodeURIComponent(uri2); // http%3A%2F%2Fjb51.net%2Fmy%20test.asp%3Fname%3Dst%C3%A5le%26car%3Dsaab // ↑ 全部結構字符都被編碼
encodeURI 用來編碼「一整個完整的 URI」。它會保留 URI 的結構,讓結果仍然是一個可辨識的位址。
encodeURIComponent 用來編碼「URI 中的某一段」,讓這一段即使含有保留字符也不會破壞整體結構。最典型的例子是拿 URL 當作另一個頁面的查詢參數:
https://www.mysite.com/send-to-friend.aspx?url=https://www.mysite.com/product.html
這個寫法是有問題的——瀏覽器會把第二個 https:// 中的 : 與 / 誤認為 URI 結構的一部分,導致整串位址解析錯誤。正確做法是編碼參數值:
https://www.mysite.com/send-to-friend.aspx?url=http%3A%2F%2Fwww.mysite.com%2Fproduct.html
ECMA-262 同時定義了 decodeURI 與 decodeURIComponent,分別用來還原這兩種編碼的結果。
若要組裝查詢字串,現代的標準做法是 URLSearchParams,它會自動處理編碼與串接:
var params = new URLSearchParams();
params.append('url', 'https://www.mysite.com/product.html');
params.toString(); // url=http%3A%2F%2Fwww.mysite.com%2Fproduct.html
另外別忘了 encodeURI 不會編碼 # 與 ?,所以在某些特殊情境(例如把整段文字當參數傳遞)仍需留意。
一句話記法:編碼整條網址用 encodeURI,編碼網址中的一個值用 encodeURIComponent。選錯的後果通常不是編碼失敗,而是伺服器收到解析錯誤的參數——這正是它難以察覺的原因。