URL 傳遞參數時,特殊字元必須經過編碼,否則會破壞 URL 結構或造成安全風險。本文整理常見特殊字元編碼對照表、編碼函式與實務防護策略。
URL 特殊字元編碼對照表
| 字元 | 用途 | 編碼 (UTF-8) | 說明 |
| 空格 | 分隔詞 | %20 或 + | query string 中常用 +,path 中用 %20 |
| + | 表示空格 | %2B | 若要傳遞實際 + 號需編碼 |
| / | 路徑分隔 | %2F | 參數值含路徑時需編碼 |
| ? | 查詢字串開始 | %3F | |
| % | 編碼前綴 | %25 | 雙重編碼常見錯誤來源 |
| # | 錨點/片段 | %23 | 參數值含 # 會被截斷 |
| & | 參數分隔 | %26 | 參數值含 & 會被誤判為新參數 |
| = | 鍵值分隔 | %3D | |
| 中文/Unicode | 非 ASCII | %E4%B8%AD%E6%96%87 | UTF-8 多位元組編碼 |
核心編碼/解碼函式
| 函式 | 用途 | 編碼範圍 | 適用場景 |
encodeURIComponent() | 編碼單一參數值 | 所有保留字元 + 非 ASCII | 最常用,參數值編碼 |
encodeURI() | 編碼完整 URL | 不編碼 : / ? # [ ] @ ! $ & ' ( ) * + , ; = | 完整 URL 已構造好時 |
decodeURIComponent() | 解碼參數值 | 對應 encodeURIComponent | 取得 URL 參數後解碼 |
decodeURI() | 解碼完整 URL | 對應 encodeURI | 較少用 |
實作範例
// 正確建構查詢字串
function buildQuery(params) {
return Object.entries(params)
.map(([k, v]) => encodeURIComponent(k) + '=' + encodeURIComponent(v))
.join('&');
}
const url = '/search?' + buildQuery({
q: 'JavaScript 教學',
category: '前端&後端',
tag: 'JS#CSS',
page: 1
});
console.log(url);
// /search?q=JavaScript%20%E6%95%99%E5%AD%B8&category=%E5%89%8D%E7%AB%AF%26%E5%BE%8C%E7%AB%AF&tag=JS%23CSS&page=1
// 解析查詢字串
function parseQuery(queryString) {
return queryString
.replace(/^\?/, '')
.split('&')
.reduce((acc, pair) => {
const [key, value] = pair.split('=').map(decodeURIComponent);
acc[key] = value;
return acc;
}, {});
}
常見錯誤與修正
| 錯誤寫法 | 問題 | 正確寫法 |
escape(str) | 已棄用,不支援 Unicode | encodeURIComponent(str) |
encodeURI(param) | 不編碼 & = 等,導致參數截斷 | encodeURIComponent(param) |
手動 str.replace('&', '%26') | 漏掉其他特殊字元、重複編碼風險 | 使用標準 API |
| 雙重編碼 | 參數值已編碼又再編碼一次 | 明確區分「原始值」與「已編碼值」 |
進階:表單提交自動編碼
<!-- GET 表單:瀏覽器自動 encodeURIComponent -->
<form action="/search" method="GET">
<input name="q" value="A&B=C">
<button type="submit">搜尋</button>
</form>
<!-- POST 表單:Content-Type 決定編碼方式 -->
<form action="/api" method="POST" enctype="application/x-www-form-urlencoded">
<input name="data" value="特殊&字元">
</form>
<!-- 檔案上傳:multipart/form-data 不編碼值本身 -->
<form action="/upload" method="POST" enctype="multipart/form-data">
<input type="file" name="file">
</form>
安全防護:輸入驗證與輸出編碼
// 白名單驗證:只允許預期字元
function validateParam(value, type) {
const patterns = {
alphanum: /^[a-zA-Z0-9]+$/,
slug: /^[a-z0-9-]+$/,
email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
safeString: /^[a-zA-Z0-9\u4e00-\u9fa5\s\-_.]+$/
};
return patterns[type]?.test(value) ?? false;
}
// 輸出到 HTML 時編碼
function escapeHtml(str) {
return str.replace(/[&<>"']/g, c => ({
'&': '&', '<': '<', '>': '>', '"': '"', "'": '''
}[c]));
}
// 輸出到 JS 字串字面值時編碼
function escapeJs(str) {
return str.replace(/[\\'"\n\r\u2028\u2029]/g, c => ({
'\\': '\\\\', "'": "\\'", '"': '\\"',
'\n': '\\n', '\r': '\\r', '\u2028': '\\u2028', '\u2029': '\\u2029'
}[c]));
}
總結
- 參數值編碼:永遠用
encodeURIComponent()
- 完整 URL 編碼:用
encodeURI()
- 解碼對應使用
decodeURIComponent()/decodeURI()
- 勿手動 replace 特殊字元,標準 API 已處理所有邊界情況
- 雙重編碼是常見 Bug,建立「原始值 → 編碼一次 → 傳輸」單向流程