URLSearchParams 怎样保留重复查询参数

如果一个接口要求提交 tag=go&tag=js，不要把重复参数先压成一个逗号字符串。URLSearchParams 会把每一组键和值保存为独立条目，关键是用 append() 追加，用 getAll() 读取全部值；get() 只返回第一个值，set() 则会覆盖同名条目。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams

先把重复参数看成多个有序条目

查询串中的两个 tag 不是同一个值被覆盖了两次，而是两个独立的键值对。URLSearchParams 会保留它们出现的顺序，因此既能表达筛选条件，也能表达用户选择的先后顺序。

下面这段最小代码可以直接说明三个方法的分工：get() 只看首个值，getAll() 才能拿到完整数组，append() 会增加一条记录。

const params = new URLSearchParams("tag=go&tag=js");

// get 只读取同名参数的第一个值。
console.log(params.get("tag"));

// getAll 按查询串中的顺序返回同名参数的全部值。
console.log(params.getAll("tag"));

// append 新增一条独立的键值记录，不删除已有 tag。
params.append("tag", "rust");
console.log(params.toString());

完整工作流：构造、读取、更新、序列化

一个不容易出错的处理顺序是：先确定每个业务值是否需要独立出现，再用 append() 写入；读取时用 getAll() 转回数组；只有明确要替换旧值时才使用 set()；最后让 toString() 负责编码和输出。

构造重复参数时优先使用 append

如果数据来自复选框、标签数组或多选控件，可以逐项调用 append()。这样每个值都有自己的条目，之后还能用 getAll() 原样取回。

const selectedTags = ["go", "js", "rust"];
const params = new URLSearchParams();

// 每个业务值占一条记录，避免数组被隐式转成逗号字符串。
for (const tag of selectedTags) {
  params.append("tag", tag);
}

// 这里会得到 ["go", "js", "rust"]。
const tags = params.getAll("tag");
console.log(tags);
console.log(params.toString());

不建议把数组直接放进普通对象再传给构造函数，例如 new URLSearchParams({ tag: ["go", "js"] })。对象形式会把属性值转换成字符串，结果通常是一个类似 tag=go%2Cjs 的单值条目，而不是两个独立的 tag。

读取时不要用 get 代替 getAll

后端接口如果允许同一个键重复出现，前端读取筛选条件时应明确选择 getAll()。get() 没有报错，只是安静地丢掉后续值，这也是“明明传了多个标签，页面只筛出一个”的常见原因。

const url = new URL("https://example.com/search?tag=go&tag=js&page=2");
const params = url.searchParams;

// 读取全部 tag，分页参数仍然按单值读取。
const tags = params.getAll("tag");
const page = params.get("page");

console.log(tags); // ["go", "js"]
console.log(page); // "2"

// URLSearchParams 可迭代，能保留查询条目的出现顺序。
for (const [key, value] of params) {
  console.log(key, value);
}

append 和 set 的区别决定数据会不会丢

这两个方法名字相近，但目的完全不同。append() 是“再加一项”，set() 是“把这个键改成唯一的新值”。如果先用 append() 添加两个标签，再调用 set("tag", "css")，最终只会保留 tag=css。

const params = new URLSearchParams();

// append 适合多选值，两个 tag 会同时存在。
params.append("tag", "go");
params.append("tag", "js");

// set 适合单值字段；它会删除已有的同名 tag。
params.set("tag", "css");

console.log(params.getAll("tag")); // ["css"]

工程上可以先给参数分类：标签、权限、状态这类多选字段使用 append()；排序字段、页码、关键字这类单值字段使用 set()。这种分类比在最后统一修补查询串更可靠。

用 toString 序列化，留意加号和百分号编码

toString() 返回适合放入 URL 的查询字符串，不包含开头的问号。空格会按 application/x-www-form-urlencoded 规则编码为 +，其它需要转义的字符会使用百分号编码。业务值应作为未编码的普通字符串交给 append()，不要先手动调用 encodeURIComponent() 再塞进去。

const params = new URLSearchParams();

// 把原始业务值交给 URLSearchParams 统一编码。
params.append("tag", "前端 工程");
params.append("tag", "C++");

// toString 不带问号，可直接拼接到 URL 的 ? 后面。
const query = params.toString();
const url = `https://example.com/search?${query}`;

console.log(query);
console.log(url);

如果查询对象来自已有的 URL，更直接的方式是使用 url.searchParams。修改它会同步影响 url.search；因此在需要保持旧 URL 文本格式完全不变的场景，应该把这次序列化差异视为一个明确的输出变化。

常见误区与检查清单

• 需要全部值却调用了 get()：改为 getAll()，并确认返回数组为空时的业务处理。
• 把数组交给对象构造函数：先逐项 append()，避免数组被转成逗号分隔的单值。
• 追加过程中误用了 set()：检查同名参数是否被覆盖，只在单值字段上使用它。
• 手动拼接未经编码的值：让 URLSearchParams 负责序列化，不要把已经编码的键和值再次编码。
• 把完整 URL 当作构造参数：构造函数处理的是查询串，完整 URL 应先取 url.search 或直接使用 url.searchParams。

常见问题

URLSearchParams 的重复参数会自动去重吗？

不会。只要通过 append() 添加，它们会作为多个条目保留；是否去重需要由业务代码自己决定。

为什么 get("tag") 只返回一个值？

这是 get() 的定义，它只返回第一个匹配值。需要所有值时使用 getAll("tag")。

set("tag", value) 能不能用来追加？

不能。set() 会删除其它同名参数并保留一个新值；追加重复参数应该使用 append()。

如何保留重复参数的顺序？

使用字符串构造或逐项 append()，再通过 getAll() 或迭代器读取。不要把参数先转换成普通对象，因为对象不表达重复键的条目结构。