Nick Blog

encodeURI vs encodeURIComponent：前端到底什麼時候該用哪個？

文章 01

#JavaScript#前端#URL

整理 encodeURI 與 encodeURIComponent 的差異，並從實務情境說明前端該在什麼時候使用。

發布於

encodeURI vs encodeURIComponent：前端到底什麼時候該用哪個？

前端在處理 URL 時，偶爾會看到：

encodeURI();
encodeURIComponent();

兩者都是做 URL 編碼，但用途不同：

  • encodeURI：處理完整 URL

  • encodeURIComponent：處理 URL 裡的一個值

不過實務上，encodeURIComponent 的使用機會通常比 encodeURI 多。

encodeURI

encodeURI() 適合處理一整條 URL。

它會編碼中文、空白等字元，但會保留 URL 本身需要的結構，例如：

:
/
?
&
=
#

例如：

const url = "https://example.com/技術文章?q=React Hook Form";

console.log(encodeURI(url));

結果：


https://example.com/%E6%8A%80%E8%A1%93%E6%96%87%E7%AB%A0?q=React%20Hook%20Form

可以看到：

  • 中文被編碼

  • 空白被編碼

  • https://、?、= 仍然保留

使用情境

假設你拿到的是一整條 URL：

const redirectUrl = "https://example.com/技術文章?title=React Hook Form";

const safeUrl = encodeURI(redirectUrl);

這時候適合用 encodeURI()，因為你希望保留整條 URL 的結構。

不過在一般前端專案裡，這種情況其實不算特別常見。

encodeURIComponent

encodeURIComponent() 適合處理 URL 裡的一個動態值。

它不會把內容當成 URL，而是把它當成單純的資料。

例如：

const keyword = "React Hook Form";

encodeURIComponent(keyword);

結果：


React%20Hook%20Form

使用情境一：搜尋關鍵字

這是比較常見的情境。

const keyword = "React Hook Form";

const url = `/search?q=${encodeURIComponent(keyword)}`;

結果：


/search?q=React%20Hook%20Form

如果搜尋內容來自使用者輸入，就更適合做編碼，因為你無法預期使用者會輸入什麼。

例如：


React Hook Form

React + TypeScript

A&B

前端 開發

使用情境二：Email 或其他動態 Query Value

例如：

const email = "user+test@example.com";

const url = `/users?email=${encodeURIComponent(email)}`;

這種情況也適合使用 encodeURIComponent()。

因為 Email、搜尋文字、名稱這類資料，本來就可能包含特殊字元。

Path Parameter 一定要 encodeURIComponent 嗎？

不一定。

例如：

const accountId = "550e8400-e29b-41d4-a716-446655440000";

const url = `/admin-users/${accountId}/password`;

如果後端已經保證 accountId 一定是 UUID，這種值本身就是 URL-safe。

因此下面這樣通常就沒問題：

const url = `/admin-users/${accountId}/password`;

你也可以寫：

const url = `/admin-users/${encodeURIComponent(accountId)}/password`;

但這裡比較偏防禦性寫法。

所以不是看到 Path Parameter 就一定要加：

encodeURIComponent();

比較重要的是看這個值的來源和格式。

如果資料格式是固定的 UUID、數字 ID：


123

456

550e8400-e29b-41d4-a716-446655440000

通常不太需要擔心。

如果值來自使用者輸入，或內容格式不固定，就比較值得做 encoding。

encodeURI 和 encodeURIComponent 的差別

可以直接這樣理解：

encodeURI("完整 URL");

處理的是：


https://example.com/技術文章?q=React Hook Form

而：

encodeURIComponent("某個值");

處理的是：


React Hook Form

所以：

| 情境 | 使用方式 |

| ———————– | ––––––––––– |

| 完整 URL | encodeURI() |

| Query Parameter Value | encodeURIComponent() |

| 使用者輸入 | encodeURIComponent() |

| 固定格式 UUID / 數字 ID | 通常不用特別處理 |

Query String 更推薦 URLSearchParams

如果只是處理一個參數，可以寫：

const url = `/search?q=${encodeURIComponent(keyword)}`;

但如果 Query Parameter 越來越多：

const url = `/search?q=${encodeURIComponent(keyword)}&page=${page}&sort=${sort}`;

就會開始不好維護。

這時候更推薦：

const params = new URLSearchParams({
  q: keyword,

  page: String(page),

  sort,
});

const url = `/search?${params.toString()}`;

URLSearchParams 會自動處理 Query String 的編碼。

在實務專案裡，這通常比自己手動拼字串更乾淨。

實務上怎麼選？

我會這樣判斷：

已經是一整條 URL

encodeURI(url);

URL 裡的一個動態值

encodeURIComponent(value);

多個 Query Parameters

new URLSearchParams();

固定格式的 UUID 或數字 ID

通常直接使用即可：

`/users/${userId}`;

總結

可以先記住最基本的差異：


encodeURI

→ 處理完整 URL

encodeURIComponent

→ 處理 URL 裡的一個值

但在實務上，更重要的是：

不要為了 encode 而 encode。

如果資料本身已經是固定格式的 UUID、數字 ID，通常不用特別處理。

真正比較常需要注意的是：

  • 搜尋文字

  • 使用者輸入

  • Email

  • 動態 Query Parameter

而 Query String 比較複雜時，直接使用 URLSearchParams 通常會更好維護。