前端開發處理 URL 參數、傳遞中文路由、API 請求構建時,字串編碼是必經關卡。JavaScript 提供三個編碼函式:escape、encodeURI、encodeURIComponent,它們的編碼範圍、適用場景截然不同。本文透過實測對比、規格解析、最佳實踐指南,幫你徹底搞懂該用哪一個。
| 函式 | 編碼範圍 | 不編碼字符 | 適用場景 | 推薦度 |
|---|---|---|---|---|
escape |
ASCII 字母、數字、* @ - _ + . / 以外皆編碼 |
* @ - _ + . / |
❌ 已棄用(MDN 標記 Deprecated) | ⭐ |
encodeURI |
完整 URI 保留字符不編碼 | ; , / ? : @ & = + $ # 及字母數字 |
編碼完整 URL(含協定、域名、路徑) | ⭐⭐⭐ |
encodeURIComponent |
URI 組件嚴格編碼 | 僅字母數字 - _ . ! ~ * ' ( ) |
編碼單一參數值、URL 片段、POST body | ⭐⭐⭐⭐⭐ |
var str = "https://localhost:8080/Product/index?id=123&attr=456&area=中國";
console.log(encodeURI(str));
// https://localhost:8080/Product/index?id=123&attr=456&area=%E4%B8%AD%E5%9C%8B
console.log(encodeURIComponent(str));
// http%3A%2F%2Flocalhost%3A8080%2FProduct%2Findex%3Fid%3D123%26attr%3D456%26area%3D%E4%B8%AD%E5%9C%8B
console.log(escape(str));
// http%3A//localhost%3A8080/Product/index%3Fid%3D123%26attr%3D456%26area%3D%u4E2D%u56FD
; , / ? : @ & = + $ #%E4%B8%AD%E5%9C%8B/ ? & = 等結構字符也編碼POST 表單欄位、路由參數%uXXXX(Unicode 代碼點),非 UTF-8/ 但編碼 ? & =,行為不一致| 場景 | 正確函式 | 錯誤示範 |
|---|---|---|
| 構建完整 URL 導向 | location.href = encodeURI(fullUrl) |
用 encodeURIComponent 導致結構被破壞 |
| 查詢參數值編碼 | encodeURIComponent(paramValue) |
用 encodeURI 導致 & = 不被編碼,注入風險 |
| POST application/x-www-form-urlencoded | encodeURIComponent(key) + '=' + encodeURIComponent(val) |
手動拼接未編碼 |
| Hash 路由參數 | encodeURIComponent(hashFragment) |
用 escape 產生 %uXXXX 格式 |
| Cookie 值設定 | encodeURIComponent(value) |
直接寫入含分號、空格的值 |
ES2015+ 提供原生 URL 構建 API,自動處理編碼,強烈建議取代手動拼接:
// 構建查詢字串
const params = new URLSearchParams();
params.append('id', 123);
params.append('attr', '中文參數');
params.append('area', '台灣');
console.log(params.toString());
// id=123&attr=%E4%B8%AD%E6%96%87%E5%8F%83%E6%95%B8&area=%E5%8F%B0%E7%81%A3
// 完整 URL 構建
const url = new URL('https://api.example.com/Product/index');
url.search = params;
console.log(url.href);
// https://api.example.com/Product/index?id=123&attr=%E4%B8%AD%E6%96%87%E5%8F%83%E6%95%B8&area=%E5%8F%B0%E7%81%A3
// 解析現有 URL
const parsed = new URL('https://example.com/?q=測試&page=2');
console.log(parsed.searchParams.get('q')); // "測試" (自動解碼)
完整網址用 encodeURI,參數值用 encodeURIComponent,escape 進博物館。
encodeURIencodeURIComponentescape → 重構移除URLSearchParams + URL