Query String 是什麼? Query String(查詢字串)是網址裡 ? 後面那一段,通常寫成 key=value,多個參數用 & 連起來,例如 https://example.com/search?q=hello&page=2 裡的 q=hello&page=2。第一次接觸多半是在搜尋頁、商品篩選、廣告追蹤網址,或是 API 文件說「請帶上 page 參數」。本文說明 Query String 的格式、哪些字元要做百分比編碼、空白為什麼有時變成 + 有時變成 %20、同名參數怎麼處理,最後整理常見用途與注意事項。
Query String 是什麼:網址 ? 後面的參數
RFC 3986(URI 的通用語法)§3.4 對 query 的定義是:query 從網址中的第一個問號(?)開始,到井字號(#)或網址結尾為止。語法規則寫成 query = *( pchar / "/" / "?" ),所以斜線和問號也可以出現在 query 裡當資料。規範同時提到,query 常用來攜帶 key=value 形式的資訊。
把一個網址拆開來看:
| 片段 | 範例 | 說明 |
|---|---|---|
| 路徑 | /search | ? 之前,指出要請求哪個資源 |
| Query String | ?q=hello&page=2 | 從第一個 ? 起,給伺服器或前端程式用的參數 |
| Fragment | #top | # 之後,# 同時是 query 的結束位置 |
這個格式裡的 & 和 = 是慣例上的分隔符號:= 分開名稱與值,& 分開不同參數。RFC 3986 把 &、=、+ 等字元列在 sub-delims(子分隔符)裡,意思是它們在網址語法中本來就可能被當成分隔用途,這也是下一節要處理編碼的原因。
Query String 常和「GET 參數」混用,兩者說的是同一個位置:GET 請求的參數放在網址的 query 裡。HTTP 請求方法的整體介紹,可前往〈淺談 HTTP 請求方法 (HTTP Request Methods):GET、POST、PUT、DELETE 基礎概念與 Fetch 入門〉。
在 JavaScript 讀取 Query String:URLSearchParams
瀏覽器和 Node.js 都有內建 URL 與 URLSearchParams。MDN 對 URLSearchParams 的說明是:這個介面提供處理網址 query string 的工具方法。下面這段程式用 URL 解析一個網址,再用 searchParams 讀參數:
const url = new URL('https://example.com/search?q=hello+world&tag=js&tag=css&empty=&flag#top');
console.log('search :', url.search);
console.log('hash :', url.hash);
console.log('q :', url.searchParams.get('q'));
console.log('tag (get) :', url.searchParams.get('tag'));
console.log('tag (getAll):', url.searchParams.getAll('tag'));
console.log('empty :', JSON.stringify(url.searchParams.get('empty')));
console.log('flag :', JSON.stringify(url.searchParams.get('flag')));
console.log('missing :', url.searchParams.get('missing'));
輸出如下:
search : ?q=hello+world&tag=js&tag=css&empty=&flag
hash : #top
q : hello world
tag (get) : js
tag (getAll): [ 'js', 'css' ]
empty : ""
flag : ""
missing : null
幾個細節對照 WHATWG URL Standard 的說明:
url.search在 query 為空時回傳空字串,否則回傳?加上 query;#top屬於hash,不在search裡。- 同名參數可以重複出現。
getAll()依出現順序回傳所有值,get()只回傳第一個。 - 解析時,
+會被還原成空白,所以hello+world讀出來是hello world。 - 沒有
=的片段(如flag)整段當作名稱、值是空字串;get()找不到名稱時回傳null,能和「有名稱但值為空」區分。

用 location.search 與 URLSearchParams 讀取目前頁面網址參數的基本寫法,這裡不重複,可前往〈JavaScript 取得 URL GET 參數:location.search 與 URLSearchParams 實作教學〉。反過來把物件轉成 Query String、處理 undefined、null 與陣列,可前往〈[JS] 將 Object 資料型態轉換為 GET 字串參數:URLSearchParams 與陣列空值處理〉。
Query String 的 URL 編碼:百分比編碼怎麼運作
網址裡不是什麼字元都能直接放。RFC 3986 §2.1 定義了百分比編碼(percent-encoding):用 % 加兩個十六進位字元表示一個位元組(pct-encoded = "%" HEXDIG HEXDIG),大小寫的十六進位字母視為相同。§2.3 列出不需要編碼的 unreserved 字元:英文字母、數字、-、.、_、~。
在 JavaScript 裡,encodeURIComponent() 負責把一段資料編成可放進網址的字串。MDN 說明它不跳脫的字元是 A-Z a-z 0-9 - _ . ! ~ * ' ( ),其他字元依 UTF-8 轉成一到四組 %XX。所以中文、空白、&、= 都會被編碼:
const word = '台灣 & C++/100%';
console.log('encodeURIComponent:', encodeURIComponent(word));
console.log('URLSearchParams :', new URLSearchParams({ q: word }).toString());
encodeURIComponent: %E5%8F%B0%E7%81%A3%20%26%20C%2B%2B%2F100%25
URLSearchParams : q=%E5%8F%B0%E7%81%A3+%26+C%2B%2B%2F100%25
可以看到「台」是 %E5%8F%B0(UTF-8 的三個位元組),& 變 %26,+ 變 %2B,/ 變 %2F,% 本身變 %25。% 也要編碼,否則解碼時會把它後面的字元當成十六進位。中文為什麼會變成三個位元組,與字元編碼有關,可前往〈ASCII 是什麼?ASCII 編碼表、控制字元與 Unicode、UTF-8 的關係〉;JavaScript 各種編碼函式的差異,可前往〈JS 中的 URL 編碼(encode)與解碼(decode)方法〉。
值裡有 & 或 = 就一定要編碼
自己用字串串接網址時,最常見的錯誤是沒有編碼就把使用者輸入放進去:
console.log('錯誤寫法:', 'https://example.com/?q=' + 'a&b=c');
console.log('正確寫法:', 'https://example.com/?q=' + encodeURIComponent('a&b=c'));
錯誤寫法: https://example.com/?q=a&b=c
正確寫法: https://example.com/?q=a%26b%3Dc
錯誤寫法的網址會被解析成 q=a 和 b=c 兩個參數,原本想傳的 a&b=c 被拆開了。正確寫法裡 & 變成 %26、= 變成 %3D,伺服器解碼後才能還原成完整的 a&b=c。用 URLSearchParams 或 url.searchParams.set() 組網址時會自動編碼,比手動串接安全。
空白變 + 還是 %20
同一個空白,有時看到 +,有時看到 %20,這是兩套規則造成的:
- WHATWG URL Standard 定義的
application/x-www-form-urlencoded序列化,會把空白(0x20)寫成+;它的編碼集合是除了英數字與* - . _之外的所有字元都要百分比編碼。URLSearchParams的toString()用的就是這套。 encodeURIComponent()把空白編成%20。
解析方向也對應:application/x-www-form-urlencoded 的解析會把 + 還原成空白,但百分比編碼的 %2B 還原後是真正的加號。下面的程式比較兩者,也看 URL.search 在改動前後的差別:
console.log('空白 %20 vs + :', encodeURIComponent('a b'), new URLSearchParams({ k: 'a b' }).toString());
const u2 = new URL('https://example.com/?k=a%20b');
console.log('URL.search 原樣 :', u2.search);
u2.searchParams.set('n', '1');
console.log('改過 searchParams後:', u2.search);
console.log('解析 + :', new URLSearchParams('q=a+b&r=a%2Bb').get('q'), '|', new URLSearchParams('q=a+b&r=a%2Bb').get('r'));
空白 %20 vs + : a%20b k=a+b
URL.search 原樣 : ?k=a%20b
改過 searchParams後: ?k=a+b&n=1
解析 + : a b | a+b
MDN 也提到這個現象:URL.search 編碼的字元是 URLSearchParams 的子集,並把空白編成 %20;但一旦透過 searchParams 修改,search 會改用 + 重新序列化。所以 ?k=a%20b 在新增一個參數後,空白變成了 +。
這個差異在多數情況不影響結果,因為兩種寫法解析後都是空白。需要留意的是:第三方 API 的簽章驗證若要求固定用 %20,就不能直接用 URLSearchParams.toString(),處理方式可前往〈JS 將 Object 轉換為 GET 字串參數〉的 encodeURIComponent 寫法。
HTML 表單用 GET 送出時會產生 Query String
不寫 JavaScript 也會產生 Query String:HTML 表單的 method 設為 get 時,瀏覽器會把欄位轉成名稱與值,用 application/x-www-form-urlencoded 序列化後,設成表單 action 網址的 query,再導向那個網址(WHATWG HTML Standard 的 form submission algorithm)。下面用一個有三個欄位的表單來看結果,其中 tag 是複選下拉選單,選了兩個值:
<form action="/search" method="get">
<input name="q" value="hello world">
<input name="lang" value="台灣">
<select name="tag" multiple>
<option selected>js</option>
<option selected>css</option>
</select>
<button>送出</button>
</form>
送出後讀取 location.search,結果如下:

空白變 +、中文變 %E5%8F%B0%E7%81%A3,複選的兩個值變成兩個同名的 tag 參數,用 getAll('tag') 讀出 ["js","css"]。同名參數重複出現不是錯誤,而是表單、API 傳遞多選值的常見做法。
Query String 的常見用途
| 用途 | 範例 | 說明 |
|---|---|---|
| 搜尋與篩選 | /search?q=關鍵字&sort=price | 把條件放進網址,重新整理或分享連結時條件仍在 |
| 分頁 | /posts?page=2&pageSize=20 | 用參數指定第幾頁、每頁幾筆 |
| 追蹤參數 | ?utm_source=newsletter | 標記流量來源,不影響頁面內容 |
| 版本字串 | /style.css?v=2 | 檔案更新時換網址,避免使用舊快取 |
| API 參數 | /api/items?limit=10 | GET 請求用 query 傳遞查詢條件 |
快取是 Query String 比較容易踩坑的地方:Cloudflare 的預設快取鍵包含查詢字串,所以 style.css?v=1 和 style.css?v=2 會被視為不同的快取項目;要把不同參數合併成同一個,Cloudflare 提供 Ignore query string 的快取層級可選。設定方式與取捨,可前往〈Cloudflare Ignore query string 設定與 Cache Key 優化實務〉。
使用 Query String 的注意事項
值一律先編碼,讀的時候交給 URLSearchParams
組網址用 URLSearchParams 或 encodeURIComponent(),讀取用 URLSearchParams,不要自己用 split('&') 與 split('=') 拆字串,否則遇到值裡有 =、+ 或百分比編碼時容易拆錯。
不要把機密資料放進網址
網址常被記在瀏覽器歷史紀錄、伺服器日誌與分享連結裡。RFC 6750 §2.3 對用 access_token query 參數傳 Token 的做法就寫明,因為含 Token 的網址很可能被記錄在日誌,除非完全無法使用標頭或請求本文,否則不應該使用。Token 的觀念與替代做法,可前往〈Access Token 是什麼?存取權杖的用途,與 Bearer Token、Refresh Token 的差異〉。密碼、Token、個人資料這類內容,改放請求標頭或請求本文。
伺服器端要把 Query String 當成不可信的輸入
網址參數任何人都能改,伺服器端要驗證型別與範圍,不能因為它「來自自己的連結」就信任。把參數拼進 SQL 之類的用途,需要另外做防護,可參考〈SQL Injection 防禦:Prepared Statements〉。
參考資料與延伸閱讀
- RFC 3986:Uniform Resource Identifier (URI): Generic Syntax(§2.1 Percent-Encoding、§2.2 Reserved Characters、§2.3 Unreserved Characters、§3.4 Query)
- WHATWG URL Standard(application/x-www-form-urlencoded 的解析與序列化、URLSearchParams、URL 的 search)
- WHATWG HTML Standard:Form submission algorithm
- MDN:URLSearchParams
- MDN:encodeURIComponent()
- RFC 6750:The OAuth 2.0 Authorization Framework: Bearer Token Usage(§2.3 URI Query Parameter)
- Cloudflare Docs:Cache keys
- 站內延伸閱讀:〈JavaScript 取得 URL GET 參數:location.search 與 URLSearchParams 實作教學〉、〈[JS] 將 Object 資料型態轉換為 GET 字串參數:URLSearchParams 與陣列空值處理〉、〈JS 中的 URL 編碼(encode)與解碼(decode)方法〉、〈Cloudflare Ignore query string 設定與 Cache Key 優化實務〉
發佈留言