URL Query 参数中加号 + 被后端误解析为空格的原理分析与 %2B 编码防御

一、问题概述：+ 在 URL Query 中变为空格的隐蔽坑点

传输包含 + 字符的数据时（例如敏感字段 Base64 串 eyJ+...），客户端若未做编码直接发送 ?token=eyJ+...，服务端在接收解析 Query 参数时，解密后字符串却变成了 eyJ ...（+ 变成了空格）。这是由于历史悠久的 application/x-www-form-urlencoded 规范规定的。

二、最小复现：直接发送加号与转换为 %2B 的解析对比

下面的对比说明了加号在后端解码阶段的两种截然不同的表现：

/* 场景 1：未编码或仅用简单 encodeURI 发送加号 */
// URL: https://api.example.com/auth?phone=+8613800000000
// 后端 decodeURIComponent("+8613800000000") -> " 8613800000000" (加号变为空格!)

/* 场景 2：将加号显式编码为 %2B */
// URL: https://api.example.com/auth?phone=%2B8613800000000
// 后端 decodeURIComponent("%2B8613800000000") -> "+8613800000000" (成功还原加号!)

三、根因分析：W3C Form URL-Encoding 历史规范与 RFC 3986 的矛盾

在传统 HTML 表单提交规范 (application/x-www-form-urlencoded) 中，空格会被编码为 +。当服务端接收到 Query 字符串按 Form 规范解码时，会将所有 + 自动替换还原为空格！而在标准 RFC 3986 中，空格编码为 %20，加号 + 属于保留字符。若要确保加号被准确识别为文本 +，必须转义为其百分号编码 %2B。

四、推荐方案：使用 %2B 转义与现代化 URLSearchParams API

1. 使用 encodeURIComponent 后，显式调用 .replace(/+/g, '%2B') 强制将加号转义为 %2B。2. 优先使用现代 JavaScript URLSearchParams API 构造查询串，它会自动在标准与 Form 规范间正确转义加号。3. 服务端若使用 Form 模式解码，需明确统一客户端与服务端的编解码标准。

五、完整代码：安全的加号编码与 Form 兼容解码函数

下面的 TypeScript 函数演示如何针对 Query 参数正确处理 + 符号编码，防范后端误解析为空格。

function safeEncodeQueryParam(paramValue: string, useFormUrlEncodedMode = false): string {
  if (useFormUrlEncodedMode) {
    // Form 规范：空格转为 +，而原本的加号 + 必须转义为 %2B
    return paramValue.replace(/%/g, "%25").replace(/\+/g, "%2B").replace(/ /g, "+");
  }
  // 标准 RFC 3986 / URLSearchParams 规范：加号编码为 %2B
  return encodeURIComponent(paramValue).replace(/\+/g, "%2B");
}

function decodeQueryParam(encodedValue: string, isFormUrlEncoded = false): string {
  if (isFormUrlEncoded) {
    // 后端按 form-urlencoded 解码：遇到 + 先替换为空格，再做 percent decode
    return decodeURIComponent(encodedValue.replace(/\+/g, " "));
  }
  return decodeURIComponent(encodedValue);
}

const base64Data = "data+key==";
const encoded = safeEncodeQueryParam(base64Data, true);
console.log(encoded); // "data%2Bkey%3D%3D"
console.log(decodeQueryParam(encoded, true)); // "data+key==" (成功还原加号)

六、常见错误方案

直接把 Base64 字符串未经编码拼接到 Query 参数后；在后端手动编写 str.replace(' ', '+') 规避问题（容易把原本真正的空格错改回加号）。

七、边界条件：POST Body 与 Query Parameter 的解码器差异

某些后端框架（如 Java Spring 或 Express body-parser）对 POST Body (application/x-www-form-urlencoded) 与 URL Query 参数使用不同的解码器，处理 + 和 %20 时需统一测试。

八、如何验证加号处理安全性

构造包含 +, %, &, =, 空格及缺失补位的 Base64 值进行端到端 API 测试；断言服务端解码结果与前端原值严格相等，并覆盖重复参数与空参数。

九、FAQ

问：为什么 encodeURIComponent('+') 返回 + 而不是 %2B？答：因为根据 RFC 3986，+ 是保留字符但允许在部分 URI 中出现，encodeURIComponent 默认不转义加号，需手动替换或由 URLSearchParams 处理。

问：空格在 URL 里究竟该用 %20 还是 +？答：标准 URL Query 推荐使用 %20；application/x-www-form-urlencoded 表单提交中使用 +。

问：Base64 字符串放到 URL 里最安全的做法是什么？答：推荐使用 URL-Safe Base64 算法（将 + 替换为 -，/ 替换为 _ 并去除 = 补位）。

十、总结

URL Query 中的 + 在传统后端解码时极易变为空格。显式将 + 编码为 %2B，或采用 URL-Safe Base64 算法，是保障敏感字符串传输安全的根本防线。