為什麼 URL 中會有 %20 或 %2F 這類字串

URL 只能安全使用特定字元。空白、非英文文字、值內的斜線、符號與保留字元,往往需要先做百分比編碼才能放進 URL。

如何為 API 與查詢參數進行 URL 編碼與解碼

DevToolKits 的 URL 編碼/解碼工具 能協助你將可讀文字轉成 URL 安全字串,並將既有的值解碼回文字。

範例:把搜尋關鍵字放進 URL

假設你想把搜尋關鍵字 Tokyo Station cafe 放進 URL。空白在某些環境下可能造成顯示或複製時出錯。

Tokyo Station cafe

URL 編碼後會變成:

Tokyo%20Station%20cafe

放進查詢參數後,就成為可分享的 URL:

https://example.com/search?q=Tokyo%20Station%20cafe

確認它能解碼回原始字串,有助於發現搜尋條件出錯或文字毀損。

編碼何時重要

在建立搜尋 URL、回呼 URL、API 查詢參數、重新導向目標與追蹤連結時,編碼尤其重要。若值未正確編碼,瀏覽器或伺服器可能會在錯誤的字元處切割,並把它解讀成不同的參數。

例如,空白依情境可能呈現為 %20 或 +。查詢值內的斜線可能需要與路徑中的斜線採取不同處理。

範例:不要重複處理回呼 URL

在 OAuth 或外部整合中,有時會把另一個 URL 當作值放進 URL 裡。

https://app.example.com/callback?next=/dashboard?tab=billing

把這種值放進 redirect_uri 時,要對作為值傳遞的 URL 部分進行編碼。

redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback%3Fnext%3D%2Fdashboard%3Ftab%3Dbilling

這裡要注意的是,已經編碼過的值又被編碼了一次。如果 % 變成了 %25,就可能是重複編碼。確認解碼後的結果是否能還原成預期的 URL,就更容易找出原因。

另外檢查查詢字串

當 URL 有許多參數時,使用 URL 參數 JSON 轉換工具 把查詢字串拆成鍵與值。這能讓你在分享或部署前,更容易審查追蹤連結與 API 請求。

這個工具的轉換規則:轉換的是「值」,而不是整個 URL

這個工具的行為與 JavaScript 的 encodeURIComponent / decodeURIComponent 相同。以下是實際的轉換結果。

輸入 編碼結果 重點
a b+c a%20b%2Bc 空白會變成 %20 而不是 +。+ 本身會變成 %2B
a/b:c@d a%2Fb%3Ac%40d /、:、@ 也會被編碼
https://example.com/a b?x=1&y=2#top https%3A%2F%2Fexample.com%2Fa%20b%3Fx%3D1%26y%3D2%23top 若放入整個 URL,連分隔用的 : / ? & = # 也會被轉換,無法再當作連結使用
it's (ok)! *~-_. it's%20(ok)!%20*~-_. 英數字與 ! ' ( ) * ~ - _ . 不會被轉換
😀 %F0%9F%98%80 UTF-8 的 4 個位元組會變成 4 個 %XX
100% 100%25 % 本身也會變成 %25

因此適合用在「查詢的值」「路徑的一段」「redirect_uri 的值」這類 URL 的零件。請只放入值來轉換,而不是整個 URL,再自行接在 ?q= 後面。 在「轉換範圍」中,除了僅限單一值(encodeURIComponent),也可選擇整個 URL(encodeURI,保留 : / ? & = #,只轉換空白與非 ASCII 文字)或表單格式(空白為 +,解碼時 + 會變回空白)。

了解解碼的行為,也有助於釐清錯誤的原因。

  • + 不會變回空白(a+b 仍是 a+b)。若想把表單形式的 + 當成空白,請先把 + 換成 %20 再解碼
  • 像 %E6%9D 這種中途被截斷的 UTF-8,或像 100% 這種 % 後面不是十六進位數字的內容,會出現 URI malformed 錯誤。請確認複製時結尾沒有漏掉
  • 像 %u3042 這種舊式寫法無法解碼,會出現錯誤

總結

URL 編碼是個小細節,卻能避免連結損壞、API 請求格式錯誤與追蹤錯誤。收到的就解碼、要送出的就編碼,並盡可能把長查詢字串當作結構化資料來審查。

常見問題

%20 與 + 都是空白嗎?

兩者都代表空白,但情境不同。在 URL 路徑與百分比編碼中,空白是 %20。在查詢字串(application/x-www-form-urlencoded)中,空白可能以 + 表示。請確認你的 API 或表單預期的格式,並用 URL 編碼/解碼工具 驗證實際送出的字串。

如何分辨雙重編碼?

% 作為值的一部分時通常會被編碼成 %25。若解碼結果含有 %25,或解碼一次後仍無法回到原始 URL,很可能是把已編碼的值再次編碼的「雙重編碼」。解碼一次並確認是否回到預期的 URL,有助於釐清原因。

URL 中的非英文字元一定要編碼嗎?

網址列可能會直接顯示,但在以連結分享或傳給 API 時,請編碼以避免因環境而毀損。例如,東京 會被編碼為其 UTF-8 位元組序列 %E6%9D%B1%E4%BA%AC。