URLSearchParams 加号与空格编码的处理方法

处理搜索条件、表单字段或 Base64 文本时，URLSearchParams 最容易让人困惑的地方就是加号。结论是：从查询字符串构造参数时，原始的 + 会按表单编码规则解释为空格；如果要表达字面量加号，应使用 %2B，或者把原始值交给 append()、set() 自动序列化。

区分原始查询串中的加号与编码后的加号

URLSearchParams 遵循 application/x-www-form-urlencoded 的解析方式。它把查询串里的 + 当作空格，把 %2B 解码成字面量 +。这也是把 Base64 片段直接拼进查询串后，读取结果少了加号的根源。

const raw = new URLSearchParams("a=A+B&b=A%2BB");

// a 中的 + 按表单查询规则变成空格，b 中的 %2B 才是字面量加号
console.log(raw.get("a")); // A B
console.log(raw.get("b")); // A+B

用 append、set 和 toString 统一生成参数

生成参数时不要手写 key=value 并拼接到 URL 后面。把未编码的业务值交给 API，序列化阶段会把字面量加号编码为 %2B，把空格编码为 +，中文和其他需要转义的字符也会得到一致结果。

const params = new URLSearchParams();

// append 保留原始业务值；不要提前调用 encodeURIComponent 再重复编码
params.append("token", "E+AXQB+BA");
params.set("keyword", "前端 查询");

const query = params.toString();
console.log(query); // token=E%2BAXQB%2BBA&keyword=%E5%89%8D%E7%AB%AF+%E6%9F%A5%E8%AF%A2

// 通过 URL 组装完整地址，避免手写 ?、& 和编码符号
const url = new URL("https://example.test/search");
url.search = query;
console.log(url.searchParams.get("token")); // E+AXQB+BA

append() 适合保留多个同名值，set() 适合明确替换某个键。本文不讨论重复键读取，但这个选择仍会影响参数容器的最终内容。

处理 URL.search 与 searchParams 的格式差异

URL.search 和 URLSearchParams.toString() 都能表示查询参数，但序列化规则不完全相同。常见差异是空格可能显示为 %20 或 +。只要解码后的值相同，就不能仅凭字符串外观判断参数被破坏。

用边界检查确认参数没有被改写

排查这类问题时，至少同时打印原始输入、toString() 和重新读取的值。只看地址栏或只看网络面板中的编码串，容易把正常的百分号编码误判成丢字符。

function assertQueryValue(input, expected) {
  const params = new URLSearchParams();
  // 统一从原始值生成查询串，再从查询串读取，模拟真实往返
  params.set("value", input);
  const serialized = params.toString();
  const actual = new URLSearchParams(serialized).get("value");
  if (actual !== expected) {
    throw new Error(`查询参数往返失败：${serialized}`);
  }
  return serialized;
}

console.log(assertQueryValue("A+B", "A+B")); // value=A%2BB
console.log(assertQueryValue("A B", "A B")); // value=A+B

如果输入已经来自完整查询串，先确认上游是否把字面量加号编码成了 %2B；如果输入是业务字符串，则不要再次手工编码。这里的边界很明确：URLSearchParams 负责参数级编码，完整 URL 的拼接和路由规则仍由调用方负责。

相关问题

为什么空格会变成加号？

这是表单查询编码的约定。它不表示空格被错误转换，重新通过 get() 读取后仍会得到空格。

什么时候必须写 %2B？

当输入文本中的加号有业务含义，例如 Base64、数学表达式或筛选条件时，应在原始查询串中使用 %2B，否则解析器会把它当成空格。

能否直接替换查询串里的加号？

不建议。查询串里未编码的加号本来就可能表示空格，盲目替换会破坏合法输入；应从未编码业务值重新调用 set() 或 append() 生成。