处理URL查询参数是前端开发中绕不开的任务，无论是发起GET请求、解析页面地址，还是封装通用的请求工具，都离不开对参数字符串的操作。过去开发者往往手动拼接字符串，不仅要自己处理问号和与号，还得操心中文编码问题，稍不注意就会产生难以排查的bug。URLSearchParams对象的出现让这件事变得简单，它是浏览器和Node.js都原生支持的API，专门用来构造、解析和操作查询字符串。
URLSearchParams的基本用法
创建一个URLSearchParams实例非常简单，可以通过多种方式初始化。最常见的是传入一个查询字符串，也可以传入一个对象或者二维数组。三种方式各有适用场景：字符串方式适合解析现成的URL，对象方式适合在代码中直接构造参数，数组方式则能表达重复的键。
// 方式一：传入查询字符串（不带问号）
const params1 = new URLSearchParams('name=tom&age=18');
// 方式二：传入对象
const params2 = new URLSearchParams({ name: 'tom', age: '18' });
// 方式三：传入二维数组，可以存在同名字段
const params3 = new URLSearchParams([['tag', 'js'], ['tag', 'web']]);
console.log(params1.get('name')); // tom
console.log(params3.getAll('tag')); // ['js', 'web']需要特别注意的是，如果传入的是字符串，参数值会被当作字符串处理，数字和布尔值都会丢失类型。另外对象方式的键值对在序列化时的顺序由对象自身属性顺序决定，如果对参数顺序有要求（比如某些接口做签名校验），建议使用数组方式明确指定顺序。
常用方法详解：增删改查一次搞懂
URLSearchParams提供了完整的方法集，覆盖了参数的所有日常操作。读取方面用get获取单个值，用getAll获取同名参数的全部值，用has判断参数是否存在。修改方面用set覆盖某个键的值，用append追加一个新值（允许同名），用delete删除指定参数。
const params = new URLSearchParams('page=1&size=10');
// 查询
params.get('page'); // '1'
params.has('size'); // true
// 修改与追加
params.set('page', '2');
params.append('tag', 'frontend');
params.append('tag', 'tutorial');
params.getAll('tag'); // ['frontend', 'tutorial']
// 删除
params.delete('size');
params.toString(); // 'page=2&tag=frontend&tag=tutorial'遍历参数有三种主流方式。第一种是for...of直接遍历实例本身，每次得到一个键值对数组；第二种是调用entries()方法，效果相同但语义更明确；第三种是用keys()或values()分别只遍历键或值。此外forEach方法也可以使用，回调函数依次接收值和键，注意顺序与数组回调一致。
const params = new URLSearchParams('a=1&b=2');
for (const [key, value] of params) {
console.log(key, value);
}
params.forEach((value, key) => {
console.log(`${key} = ${value}`);
});有一个容易忽略的细节：set方法会删除该键原有的所有值再写入新值，而append会保留原有值并追加。如果接口不允许重复参数，误用append可能导致服务端解析出数组而报错，这一点在实际开发中需要留意。
自动编码：告别手动encodeURIComponent
URLSearchParams最大的便利之一是自动处理URL编码。当参数值包含中文、空格、特殊符号时，它会自动按照规范进行百分号编码，开发者完全不需要手动调用encodeURIComponent。反过来，解析时它也会自动解码，读取到的就是原始字符串。
const params = new URLSearchParams();
params.set('keyword', '前端 开发&入门');
params.set('redirect', 'https://ipipp.com/home');
console.log(params.toString());
// keyword=%E5%89%8D%E7%AB%AF+%E5%BC%80%E5%8F%91%26%E5%85%A5%E9%97%A8&redirect=https%3A%2F%2Fipipp.com%2Fhome可以看到空格被编码成加号，中文被编码成UTF-8百分号序列，与号也被正确转义，整个字符串可以直接拼接到URL后面使用。对比手动拼接，如果忘了编码中文，某些浏览器或服务端会直接返回400错误，而且问题往往只在特定参数出现时才暴露，排查成本很高。使用URLSearchParams可以从根源上杜绝这类问题。
另一个实用技巧是配合URL对象一起使用。URL实例的searchParams属性就是一个现成的URLSearchParams对象，可以直接读取或修改地址栏参数，非常适合解析location.href的场景。
const url = new URL('https://ipipp.com/list?page=3&cat=js');
console.log(url.searchParams.get('page')); // '3'
// 修改后重新获取完整地址
url.searchParams.set('page', '4');
console.log(url.href); // https://ipipp.com/list?page=4&cat=js与fetch和axios结合发起网络请求
在发送GET请求时，URLSearchParams可以直接作为fetch的body参数，也可以用toString方法拼接到URL上。一个鲜为人知的特性是，fetch在POST请求中如果直接传入URLSearchParams实例，会自动把请求头的Content-Type设置为application/x-www-form-urlencoded，服务端按表单方式解析即可，非常适合对接传统表单接口。
// GET请求拼接参数
const params = new URLSearchParams({ userId: 1001, fields: 'name,avatar' });
fetch(`https://ipipp.com/api/user?${params}`)
.then(res => res.json())
.then(data => console.log(data));
// POST请求，自动设置表单类型的Content-Type
const form = new URLSearchParams();
form.append('title', '文章标题');
form.append('content', '正文内容');
fetch('https://ipipp.com/api/post', {
method: 'POST',
body: form
}).then(res => res.json());如果项目中使用axios，同样可以受益于URLSearchParams。GET请求中用params配置项传入普通对象即可，axios内部会自动序列化；而在POST场景下，把URLSearchParams实例直接作为data传入，axios会检测到它的类型并按表单方式提交，省去了手动设置请求头和引入qs库的过程。
import axios from 'axios';
// POST提交表单格式的数据
const payload = new URLSearchParams({ action: 'login', role: 'admin' });
axios.post('https://ipipp.com/api/session', payload)
.then(res => console.log(res.data));需要注意兼容性问题。URLSearchParams在主流现代浏览器和Node.js 10以上版本都可用，但如果项目要兼容IE，就需要引入对应的polyfill，或者改用qs这类第三方库。另外在构造函数中直接传对象时，值为undefined或null的属性会被序列化成字符串形式的undefined，提交前最好先做一层过滤，把无效值剔除掉，避免服务端收到脏数据。
总的来说，URLSearchParams以极低的学习成本解决了查询参数处理这个高频问题，配合URL对象和fetch使用更是相得益彰。在下一个需要拼接参数的场景里，不妨放下手动的字符串拼接，让这个原生API帮你把编码、解析、序列化的细节全部处理妥当。
URLSearchParamsJavaScript网络请求查询参数修改时间：2026-09-12 21:26:35