深入对比 encodeURI 与 encodeURIComponent：RFC 3986 保留字符与场景落地

一、问题概述：保留字符 (Reserved Characters) 编码行为差异

RFC 3986 定义了 URL 规范中的保留字符集（如 :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =）。encodeURI 用于对“完整 URL”进行编码，它会保留架构与路径分隔符（如 https:// 和 ?）；而 encodeURIComponent 用于对“URL Query 的具体参数 Key 或 Value”进行编码，会将包括 /, ?, =, & 在内的所有保留字符全量转义为百分号编码 (%XX)。

二、最小复现：误用 encodeURI 编码 Query 参数导致解析截断

当请求参数本身包含 & 或 = 符号（如重定向 URL 参数）时，如果使用 encodeURI 编码该参数，& 不会被转义，导致后端 URL 解析器将其误认为是多个独立的 Query 参数。

const redirectTarget = "https://site.com/login?ref=123&lang=cn";

/* 错误做法：使用 encodeURI 编码参数值，& 未被转义为 %26 */
const wrongUrl = "https://api.example.com/redirect?target=" + encodeURI(redirectTarget);
// 结果包含原样 &：https://api.example.com/redirect?target=https://site.com/login?ref=123&lang=cn
// 后端会将 &lang=cn 误解析为 api.example.com 的独立参数！

/* 正确做法：使用 encodeURIComponent 编码参数值 */
const correctUrl = "https://api.example.com/redirect?target=" + encodeURIComponent(redirectTarget);
// 结果转义保留字符：https://api.example.com/redirect?target=https%3A%2F%2Fsite.com%2Flogin%3Fref%3D123%26lang%3Dcn

三、根因分析：URL 语法结构解析与字符集分类

URL 语法结构分为 Scheme、Authority、Path、Query 与 Fragment。encodeURI 假设输入是完整的 URI 框架，因此不转义语法保留字符；encodeURIComponent 假设输入仅为 URI 树中的组件片段（Component），必须将任何可能破坏 URI 语法的控制与分隔字符完全百分号转义。

四、推荐方案：按 URL 组成部分分层编码

1. 完整 URL 基础结构：使用 encodeURI 或原生 new URL() 构造函数。2. Query 查询参数的 Key/Value：必须使用 encodeURIComponent 或 URLSearchParams API。3. 动态 Path 路径段：单独对路径段调用 encodeURIComponent 并用 / 重新拼接。

五、完整代码：分层 URL 安全构建纯函数

下面的 TypeScript 函数演示如何针对完整 URL 基础框架、Path 段与 Query 参数值分别施加正确的编码策略。

function safeBuildUrl(baseUrl: string, pathSegment: string, queryParams: Record<string, string>): string {
  // 1. 动态 Path 路径段编码 (按 / 切分后分别转义)
  const encodedPath = pathSegment.split("/").map(encodeURIComponent).join("/");

  // 2. Query 参数 Key/Value 编码 (完全转义保留字符)
  const queryParts: string[] = [];
  for (const [key, val] of Object.entries(queryParams)) {
    const safeKey = encodeURIComponent(key);
    const safeVal = encodeURIComponent(val);
    queryParts.push(safeKey + "=" + safeVal);
  }

  const queryString = queryParts.join("&");
  const cleanBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
  const fullRawUrl = cleanBase + "/" + encodedPath + "?" + queryString;
  return encodeURI(fullRawUrl);
}

console.log(safeBuildUrl("https://api.example.com", "v1/user info", { search: "a&b=c", redirect: "https://site.com?id=1" }));
// 路径空格转为 %20，query 中的 & 和 = 被安全转义

六、常见错误方案

对整条包含 ?key=value 的 URL 直接调用 encodeURIComponent（导致 https:// 和 ? 全部被破坏）；对传入的 Query 参数值使用 encodeURI（导致参数分隔符泄露）。

七、边界条件：单引号、波浪号与 Unicode 补充字符

encodeURI 和 encodeURIComponent 不转义 ' ! ( ) * ~ 等字符；若服务端对 RFC 3986 存在严格校验，需手工补充对单引号和括号的百分号替换。

八、如何验证 URL 编码正确性

断言 new URL(url).searchParams.get(key) 能原样还原值；覆盖 &, =, ?, /, #, %、空格与 Unicode，并用真实客户端/服务端往返测试确认双方采用相同编码规则。

九、FAQ

问：encodeURI 和 encodeURIComponent 哪个性能更好？答：两者性能相当，核心区别在于转义字符集的规范定义，而非执行速度。

问：为什么 new URLSearchParams() 比手动 encodeURIComponent 更好？答：URLSearchParams 会自动处理键值对编码与 +/%20 规范，减少手动拼接拼接错漏。

问：何时使用 escape()？答：escape() 是废弃的非标准 API，无法正确处理 Unicode 补充字符，绝不应在现代化开发中使用。

十、总结

牢记编码分工：完整 URL 框架用 encodeURI 或 new URL()；参数 Component 用 encodeURIComponent 或 URLSearchParams；杜绝一刀切式的全量混用。