返回探索
指南VibeFix 内容整理更新于 2026年11月19日

别再手拼地址了:用 URL 与 URLSearchParams 管查询参数

前端每天都在拼地址、读地址、改地址,拼错了就是实打实的 bug。本文按 MDN 的 URL 与 URLSearchParams 官方文档讲清楚:地址拆零件、相对地址解析、get 与 getAll、加号编码陷阱、空值误判与哈希片段。

真实照片:双手在笔记本键盘上敲代码,背景里一只白色咖啡杯虚化

先把这篇的边界说清楚。站里已经有《搜索功能实战》,讲的是搜索框怎么做、搜索结果怎么排;还有《深链接实战》,讲的是链接怎么跳进应用里的指定页面——那两篇讲的都是链接的用途。这篇讲的是更底层的东西:地址本身。前端每天都在拼地址、读地址、改地址,分享链接里多个参数、筛选条件一改地址就变、复制过来的地址带了一堆跟踪参数,这些活看着琐碎,拼错了就是实打实的 bug。URL 接口和 URLSearchParams 就是浏览器给你的现成工具,不用再手写字符串拼接那套土办法了。

下面用到的“山野民宿”是一个虚构的练手项目:一个帮山里民宿做展示和预订的网页小工具,房客按日期、人数、价格筛选房间,筛选条件就写在地址栏的查询参数里,分享链接就是把地址整个复制过去。本文所有以它为例的操作、代码和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于 URL 与 URLSearchParams 的属性、方法和行为,都来自 MDN 的 URL 与 URLSearchParams 官方文档,来源见每篇的 meta 信息与 evidence 记录。MDN 文档里的例子,比如 example.com 上的地址,都是文档自带的示例域名,不是真实网站。

先拆开一个地址:URL 把字符串变成零件

一个地址看起来是一整串字符,其实是由一堆零件拼成的。协议、主机、端口、路径、查询参数、哈希片段,各有各的位置,也各有各的规矩。手写字符串拼接的问题就出在这里:你得自己记住问号只出现一次、& 号分隔每一对、# 号后面的东西不属于查询参数,漏一个符号,整个地址就歪了。URL 接口的做法是反过来的:你给它一个字符串,它帮你拆成零件,每个零件都能单独读、单独改,改完再拼回去,拼回去的结果一定是合法的。

用法很简单:const url = new URL("https://example.com/rooms?city=hangzhou&guests=2#top")。建好之后,url.protocol 是 https:,url.hostname 是 example.com,url.pathname 是 /rooms,url.search 是 ?city=hangzhou&guests=2,url.hash 是 #top,url.origin 是 https://example.com,url.href 是整个地址。想改路径就改 url.pathname,想改哈希就改 url.hash,改完 url.href 自动跟着变。MDN 文档里还有一个细节:给 url.pathname 赋一个带中文的值,比如 démonstration.html,浏览器会按 RFC 3986 的规则自动编码,href 里出现的是 /d%C3%A9monstration.html,不用你手动算百分号编码。

URL 构造函数还有第二个参数:基准地址。new URL("cats", "http://www.example.com/animals/dogs") 的结果不是 http://www.example.com/animals/dogs/cats,而是 http://www.example.com/animals/cats。因为 dogs 在这个基准地址里是文件名那一段,没有结尾斜杠,相对地址是相对于目录部分解析的。山野民宿里有个真实教训:详情页地址是 /rooms/12,代码用它当基准去拼相对地址 photos,结果拼到了 /rooms/photos,而不是想要的 /rooms/12/photos。修法是基准地址末尾补一个斜杠,或者直接用绝对路径拼,别把相对解析的规矩交给直觉。

地址非法怎么办:先问能不能解析,再建对象

URL 构造函数遇到解析不了的地址会直接抛异常。用户在输入框里贴进来的地址、从别的系统同步过来的链接、分享出去又被聊天软件截断的地址,都有可能非法。MDN 给了两种处理办法:一种是 try...catch 包住 new URL,抛了异常就走兜底逻辑;另一种是先用 URL.canParse() 问一句能不能解析,能解析再建对象,不能解析就提示用户。两种办法效果一样,canParse 的写法更干净,不用为了判断而故意触发一次异常。

还有一个更安静的办法:URL.parse()。它和构造函数做的是同一件事,区别是解析失败时返回 null,而不是抛异常。调用方只要判断返回值是不是 null,就能决定下一步。三种办法选哪个,取决于你的代码风格:已经在用 try...catch 的地方用构造函数,纯判断的地方用 canParse 或 parse。共同点只有一个:永远别假设用户给的地址一定合法,非法地址是常态,不是例外。

查询参数:URLSearchParams 是专门管问号后面的工具

地址里问号后面的部分叫查询参数,是一组用 & 连起来的键值对。读它、改它、拼它,都有专门的工具 URLSearchParams,不用再手写 split("&") 再 split("=") 那套。最常见的用法是从当前页面地址里读参数:const params = new URL(window.location.href).searchParams,params.get("id") 就能拿到 id 的值。山野民宿的筛选页就是这样:地址栏里写着 ?city=hangzhou&guests=2&price=300-600,页面一加载就从 searchParams 里把三个值读出来,恢复筛选状态,刷新页面也不会丢。

URLSearchParams 的方法分三类:读、改、查。读的有 get()、getAll()、keys()、values()、entries(),还有一个只读的 size 属性,告诉你一共有多少个参数条目。改的有 append()、set()、delete()、sort()。查的有 has(),能问“有没有这个参数”,也能问“有没有这个参数和这个值”。MDN 文档里的例子把这些方法串在了一起:从 q=URLUtils.searchParams&topic=api 开始,has("topic") 是 true,get("topic") 是 api,append("topic", "webdev") 之后再 toString(),结果是 q=URLUtils.searchParams&topic=api&topic=webdev,多了一个同名参数。

这里有个必须记住的区别:get() 只返回第一个值,getAll() 返回全部值。地址里写着 foo=bar&foo=baz,get("foo") 只给你 bar,getAll("foo") 才给你 ["bar", "baz"] 两个。山野民宿的筛选支持多选城市,地址里会出现 city=hangzhou&city= suzhou 这样的重复参数,只用 get() 就会悄悄丢掉后面的选择,用户明明选了两个城市,页面却只按一个筛选。set() 也有类似的脾气:它会把指定键的所有旧值删掉,只留一个新值。想保留多个值就用 append(),想只留一个就用 set(),选错了,筛选条件就悄悄变了样。

编码:加号、百分号与两次编码的坑

查询参数里的编码是最容易翻车的地方。URLSearchParams 在序列化的时候,会把除了字母数字和 * - . _ 之外的字符都做百分号编码,空格编码成加号 +。反过来解析的时候,加号又会被当成空格解回来。MDN 文档里有个很能说明问题的例子:base64 编码的结果里常有加号,比如 E+AXQB+A,直接把它拼进查询字符串 new URLSearchParams(`bin=${base64Data}`),再用 get("bin") 读出来,加号全变成了空格,变成 E AXQB A,再解码就对不上原文了。正确做法是别拼字符串,用 append() 方法:searchParams.append("bin", base64Data),它会把加号编码成 %2B,读出来还是原来的 E+AXQB+A。

教训可以总结成一句话:永远别用字符串插值拼查询参数。模板字符串看着方便,但它绕过了编码,特殊字符原样进了地址,读回来就变了样。append() 和 set() 会把编码这件事接过去,你只管给没编码过的原始值。反过来也一样:从 URLSearchParams 里读出来的键和值,都是已经解码过的,别再对它们调用一次 decodeURIComponent,否则百分号本身会被再解一次,%2524 这种双重编码就是这么来的。

还有一个细节藏在 URL.searchParams 和 URL.search 的配合里。改 searchParams 会同步改掉 URL 的 search,但两边的编码规则不完全一样:URL.search 把空格编码成 %20,而 URLSearchParams 把空格编码成 +。MDN 的例子写得很直白:地址 https://example.com/?a=b ~,url.searchParams.toString() 是 a=b+%7E,调用一次 url.searchParams.sort() 之后,哪怕值完全没变,整个地址的序列化结果也变了,href 变成 https://example.com/?a=b+%7E。排序本身没错,但它会顺带重写整个查询串。所以别在没必要的时候调用 sort(),也别以为“只是读一下参数”就不会改变地址,读和改之间只有一步之遥。

空值、缺等号与重复键:三种容易误判的情况

查询参数里有三种长得像、意思却不一样的情况。第一种是 foo=,等号后面什么都没有,get("foo") 返回空字符串。第二种是 foo,等号都没有,get("foo") 同样返回空字符串。URLSearchParams 不区分这两种情况,toString() 之后两者都变成 foo=。第三种是参数根本不存在,get("foo") 返回 null。空字符串和 null 是两回事:前者是“用户给了这个参数、值是空的”,后者是“用户根本没给这个参数”。山野民宿的筛选里,price= 空着和压根没有 price 参数,意思完全不同:前者可能是用户清空了价格,后者是用户还没碰过价格筛选。写代码的时候先用 has() 判断存不存在,再用 get() 读值,别把空字符串和 null 混成一团。

重复键是另一种误判来源。上面说过,get() 只取第一个,getAll() 才取全部。还有一种情况是 delete():不带第二个参数时,它会删掉指定键的全部值;带上值的时候,只删掉那一对。想删掉某一个城市、保留另一个,就得把值也传进去。sort() 则按字母顺序排键,排完之后重复键的相对顺序保持不变。这些行为 MDN 文档里都有明确的例子,写之前先读一遍,比上线后排查要便宜得多。

翻车现场:五种最常见的地址处理事故

下面这张图是虚构的山野民宿项目一个季度里 64 次地址处理事故的分布:手拼字符串漏了问号或 & 号 22 次,编码处理不当导致参数变样 14 次,只用 get() 读重复参数丢了后面的值 12 次,相对地址基准算错拼错路径 9 次,改查询参数时顺手丢了哈希片段 7 次。22 加 14 加 12 加 9 加 7 等于 64,账是平的。这些数字是编出来讲道理的,但每一类事故都是真实项目里反复出现的,值得一条一条对照检查。

虚构山野民宿项目一个季度 64 次地址处理事故的原因分布条形图:手拼字符串 22 次、编码不当 14 次、只取首值 12 次、相对路径算错 9 次、丢失哈希片段 7 次

第一类是手拼字符串。问号写了两次、& 号漏了、值里的 & 没编码,都会把一个参数劈成两个,或者把两个参数粘成一个。修法是彻底不用字符串拼接,改用 URL 和 URLSearchParams,拼接的活交给浏览器。第二类是编码不当。加号变空格、百分号被解两次、中文没编码直接进地址,都是编码环节没交给正确工具的后果。记住:给值的时候给原始值,读值的时候读解码后的值,编码只发生在序列化那一刻。

第三类是只取首值。多选参数用 get() 读,丢掉的不是数据,是用户的选择。凡是可能重复的参数,一律用 getAll()。第四类是相对地址算错。基准地址末尾有没有斜杠,结果完全不同,拼之前先打印一次解析结果,确认路径是你想要的那条。第五类是丢哈希。改 url.search 或者重新拼 href 的时候,#top 这种片段很容易被顺手丢掉,用户点分享链接进来,本来该定位到的位置没了。改查询参数只动 searchParams,别整串重写,哈希就丢不了。

分享链接与筛选状态:把地址当成应用状态来管

地址栏的查询参数有个天然的好处:它就是应用状态的免费存储。筛选条件写进地址,刷新页面还在,复制地址发给朋友,对方打开就是同一套筛选结果,不用登录、不用后端、不用本地存储。山野民宿的筛选页就是这么做的:城市、人数、价格区间、入住日期,全部写进查询参数,用户每改一次筛选,代码就用 history.replaceState 把新地址写进地址栏,不刷新页面,只换地址。

这里有几个实操要点。第一,参数名要短而稳,city 比 selectedCity 好,改名字就是改分享出去的老链接,旧链接里的参数会读不到。第二,默认值别写进地址。人数默认是 2,就别把 guests=2 写进去,地址越短越好读,也越好分享;读的时候,没有这个参数就用默认值。第三,敏感信息别放进地址。查询参数会进浏览器历史、进服务器日志、进分享出去的链接, token、手机号、身份证号,一律不许出现。第四,参数值要做校验。地址是用户能直接改的,price=abc 这种非法值必须被挡下来,读出来先校验再用,别直接拿去渲染。

第五,排序和去重。同一套筛选条件,参数顺序不同,地址看起来就是两个链接,分享出去容易让人困惑。写入的时候固定一个顺序,或者调用 sort() 统一排一遍,地址就稳定了。第六,别把整个应用状态都塞进地址。地址适合放筛选、分页、当前标签页这种轻量状态,放不下大段文本和复杂对象,超过了就该用别的状态管理方式。地址是状态的快照,不是数据库。

写地址处理代码的工作流:先解析,再相信

给 AI 生成的项目写地址处理代码,建议固定一套流程。第一步,拿到地址先解析,别急着用字符串方法切。new URL() 或者 URL.parse() 先走一遍,非法地址在这里就拦下来,别让它流到后面。第二步,读参数用 searchParams,getAll() 读多值,has() 先判断存在,get() 读单个值,分工固定下来,就不会出现“读错了还不知道”的情况。第三步,改参数用 set()、append()、delete(),别拼字符串,编码交给浏览器。

第四步,写测试的时候准备三组地址:正常的、带特殊字符的、非法的。带中文的城市名、带加号的 base64 值、带重复参数的多选、缺等号的空参数、非法字符拼成的地址,都该出现在测试里。第五步,拿真实分享链接做一次端到端验证:复制地址、发到聊天软件、从聊天软件里点开,看看参数是不是都还在。聊天软件有时会截断地址、转义字符,这一步能抓到开发环境里永远遇不到的问题。第六步,定期检查分享出去的老链接还能不能用。参数名一改,老链接就失效,改参数名之前先想想有多少人手里还攥着老链接。

哈希片段不是查询参数:井号后面是另一回事

地址里井号 # 后面的部分叫哈希片段,它和查询参数是两套东西。查询参数发给服务器,哈希片段不发,浏览器只在本地用它定位页面里的锚点,或者交给前端路由当页面状态。山野民宿的房型详情页用 #photos 定位到照片区,用 ?room=12 告诉服务器要看哪间房,两者各管各的。手写字符串拼接最容易在这里翻车:把查询参数拼到井号后面去,服务器就读不到了;或者改查询参数的时候把整串地址重写一遍,井号后面的定位信息就丢了。

URL 接口把这两者分得很清:url.search 管问号后面的部分,url.hash 管井号后面的部分,改一个不会动另一个。读当前页面的哈希用 window.location.hash,改它用 url.hash = "photos",浏览器会直接跳到对应位置,不刷新页面。前端路由里常见的 hash 模式就是靠这个机制:地址栏里 # 后面的路径一变,页面内容跟着换,服务器却始终只看到同一个地址。记住这条分工:要传给服务器的东西放查询参数,只在浏览器本地用的定位和状态放哈希片段,两者别混着用,混了就得同时修两处。

最后提醒一句:地址处理代码的最高境界,是让用户感觉不到它的存在。筛选一改地址就变,地址一分享结果就对,刷新页面状态还在,复制粘贴不会丢参数。做到这四点,地址栏就从一串难看的字符,变成了应用最可靠的状态同步方式。工具已经在浏览器里了,不用再手写拼接,也不用再为一个问号漏没漏这种事熬夜排查。

阅读 2评论 0

评论 (0)

ME
0/1000
评论加载中...

原始来源

浏览项目广场发布你的项目

相关文章

真实照片:一名女子站在办公室白墙前,把彩色便利贴按行贴在墙上,手里还拿着一张粉色便利贴
指南
别再用 margin 硬凑间距了:Flexbox 一维布局实战指南

Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。

开发工作流前端工程AI 编程实践
真实照片:俯拍一双手在深色桌面上整理写了字的索引卡片,旁边是夹着表格的写字板
指南
数据先装进盒子再说话:对象与 JSON 实战指南

一张点单就是一个对象:桌号、菜品、总价、付没付钱,全按标签收在一起。本文按 MDN 的《Working with objects》《JSON》《Object》三篇官方文档讲清楚:对象字面量、点号与方括号、增删改查、for...in 配 hasOwn、方法与 this、getter 与 setter、引用与复制、Object.assign 等工具箱、空白原型对象、JSON 的严规矩,以及 stringify 与 parse 和数字精度的坑。

开发工作流前端工程AI 编程实践
真实照片:一双手在 MacBook Pro 上打字,屏幕显示改写 HTML 内容的 JavaScript 代码,白色桌面上有白色鼠标、纸张和文件夹
指南
别让函数把你绕晕:JavaScript 函数、参数与箭头函数实战指南

函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。

工具技巧前端工程AI 编程实践