URL 编码与传参避坑

一、场景:参数到服务端就变样了

"我明明传了 a=1&b=2,后端只收到 a。"——十有八九是参数值里含未编码的特殊字符,把后面的参数吞掉了。URL 是一套严格语法:保留字符(&、=、?、#、空格等)出现在参数值里时必须转义,否则会被解析器当成语法的一部分。

二、两个编码函数,千万别用错

JavaScript 提供两个编码函数,差异经常被忽略:

• encodeURIComponent:转义几乎所有保留字符,包括 & 和 =。用于编码单个参数值——这是 90% 场景的正确选择;
• encodeURI:保留 URL 结构字符,用于编码整条 URL。如果拿它编码参数值,& 不会被转义,后端解析时参数就被截断了。

打开 URL 编解码 做个对照实验:输入 a=1&b=2,分别用两种模式编码,看输出里 & 是否变成 %26。解码同理——工具同时给出两种模式的互转结果。

三、高频坑清单

• 空格变加号:表单(application/x-www-form-urlencoded)规则里空格编码为 +,而 encodeURIComponent 输出 %20。若用表单规则解码按标准规则编码的字符串,空格会变成加号。签名计算前务必统一编码规则;
• 中文乱码:历史编码(GBK)与 UTF-8 混用导致。统一 UTF-8 后用解码工具验证:解码结果正常说明编码侧没问题,乱码则出在编码字符集;
• # 后的内容丢失:井号是 fragment 分隔符,参数值里的 # 不编码的话,它后面的内容根本不会发到服务器。SPA 路由的 hash 也受此影响,路由参数务必编码;
• 嵌套 JSON 参数:把 JSON 塞进参数的标准姿势:JSON 工具压缩 → encodeURIComponent → 拼接。服务端先按参数解码再 JSON.parse。任何一步漏掉编码,花括号引号都会破坏外层 URL 结构。

四、签名不匹配的排查

调用需要签名的第三方 API 时,最常见的失败原因是"签名的原文与服务端不一致"。排查方法:

• 把待签名字符串完整粘贴到 URL 编解码 工具,看编码后的形态是否符合服务端文档要求(空格是 %20 还是 +、哪些字符不转义);
• 对比请求实际发出的 URL(浏览器 Network 面板复制)与你的预期,差异点通常就是签名不一致的来源;
• 涉及 Base64 的签名,用 Base64 编解码 核对填充与字符集(+ / 还是 - _)。

五、常见问题

• 解码报错:孤立的 % 字符不是合法编码(必须跟两位十六进制),检查是否重复编码或手工拼接出错;
• query 参数解析:URL 工具的解析模式可以直接拆出协议、主机、路径与全部参数键值对,比肉眼数 & 靠谱;
• 双重编码:输出里出现 %2520 说明编码了两次(20 的 % 又被编码成 %25),排查哪一层多做了一次。

六、小结

URL 问题的万能排查法:把"你以为是的内容"和"实际发出的内容"都放到解码工具里对比,差异一目了然。规则记三条:参数值用 encodeURIComponent、统一 UTF-8、签名前核对编码规范。