URLSearchParams 怎样删除指定键的全部参数值

如果查询字符串里有多个同名参数，例如 ?tag=go&tag=js&page=2，想一次删掉全部 tag，不要只改原字符串。把它交给 URLSearchParams 后调用 delete("tag") 即可；这个调用会移除所有名称匹配的参数和值，page=2 会继续保留。

参考地址：https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/delete

本文只解决“按键名全量删除”这个任务，再补充带值删除和回写 URL 时最容易混淆的边界。

先看清重复键是什么

URLSearchParams 不是普通对象，它保留查询参数的顺序，也允许同一个名称出现多次。因此 get("tag") 只能取到一个值，检查重复项时应使用 getAll("tag")。

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

// 用 getAll 确认同名键有多个值，再决定是否整组删除。
console.log(params.getAll("tag")); // ["go", "js"]
console.log(params.toString());     // tag=go&tag=js&page=2

用 delete(name) 删除指定键的全部值

最小写法只有两步：拿到参数对象，传入要删除的名称。delete() 的返回值是 undefined，所以不要把返回值当成“删除了几项”；删除后的状态应通过 has()、getAll() 或 toString() 判断。

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

// 只按名称匹配，tag=go 和 tag=js 会一起删除。
params.delete("tag");

console.log(params.has("tag"));   // false
console.log(params.getAll("tag")); // []
console.log(params.toString());   // page=2

这里的关键不是循环调用 delete()，而是一次按名称匹配整个参数列表。若键名不存在，调用也不会抛异常，序列化结果保持不变。

删除后怎样写回 URL

如果对象来自 url.searchParams，它与 URL 实例关联，修改参数后读取 url.href 就能得到更新后的地址。若对象是单独构造的，则使用 params.toString() 取得查询部分，再决定是否拼接到其它路径。

const url = new URL("https://example.com/list?tag=go&tag=js&page=2#top");

// searchParams 与 url 关联，删除会同步影响 URL 的查询部分。
url.searchParams.delete("tag");

console.log(url.search); // ?page=2
console.log(url.href);   // https://example.com/list?page=2#top

不要直接用字符串替换 "tag=go"：它无法可靠处理重复键、编码字符、空值和参数顺序。需要保留路径与哈希时，让 URL 负责回写更稳妥。

带 value 参数时，匹配范围会改变

现代实现还支持 delete(name, value)：只有名称和值同时匹配的项才会删除。例如下面的代码保留 tag=js，只删掉 tag=go。

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

// 名称和值同时匹配，因此两个 tag=go 被删除，tag=js 保留。
params.delete("tag", "go");

console.log(params.toString()); // tag=js&page=2

如果需要兼容不支持第二个参数的旧环境，不能只看方法签名。可以先读取 getAll(name)，再构造一个新的参数对象，或根据项目的浏览器支持范围选择 polyfill。对于只要求“同名全部删除”的场景，单参数 delete(name) 是最直接的写法。

一个可复用的删除函数

下面的函数只改查询参数，不改变原 URL 的路径、片段和其它键；空查询串时也不会留下多余的问号。

function removeQueryKey(input, key) {
  const url = new URL(input);

  // URL 负责处理编码、路径和 hash，delete 负责移除同名参数集合。
  url.searchParams.delete(key);
  return url.toString();
}

console.log(
  removeQueryKey("https://example.com/list?tag=go&tag=js&page=2#top", "tag"),
); // https://example.com/list?page=2#top

核对结果时，重点看三件事：目标键的 has() 是否为 false；其它键是否仍在；最终 URL 是否保留预期的路径和哈希。

常见疑问

调用 delete 后为什么 URL 没变？ 如果使用的是独立的 new URLSearchParams()，它不会自动修改某个 URL 字符串，需要读取 params.toString() 或直接操作 url.searchParams。

delete("tag") 会删除第一个还是全部？ 会删除所有名称为 tag 的参数；只有传入第二个参数时，才会进一步按值缩小匹配范围。

怎样确认没有误删？ 删除前用 getAll() 记录同名值，删除后检查 has() 与 toString()，同时确认不相关的参数仍然存在。

因此，按键名清理重复查询参数时直接使用 URLSearchParams.delete(name)；需要保留同名的其它值时，再使用带值形式并提前确认目标浏览器的支持范围。