URL 查询参数编码指南

这个页面解决什么问题

URL 编码错误通常不是“中文没有编码”这么简单，而是把完整 URL、路径、参数名、参数值和 fragment 混在一起处理。查询参数值里出现 &、=、?、#、空格、中文或斜杠时，如果没有按组件编码，服务器会把一个值拆成多个参数或丢失片段。

这个页面适合排查搜索条件、回调地址、广告追踪参数、Webhook URL、OAuth redirect_uri 和内部跳转链接。重点是先拆结构，再编码值。

快速判断

• 参数值里含有 & 或 =，必须编码，否则会被当成分隔符。
• 完整 URL 不应整体用 encodeURIComponent 后直接访问。
• 回调地址作为参数值时，需要对嵌套 URL 做组件级编码。
• 看到 %25 大量出现，可能是重复编码。

可复制示例：错误输入与修复后输入

坏样例把回调 URL 直接拼到 query 中；修复样例对 redirect_uri 参数值编码。

https://example.com/login?redirect=https://app.example.com/a?x=1&y=2

https://example.com/login?redirect=https%3A%2F%2Fapp.example.com%2Fa%3Fx%3D1%26y%3D2

坏样例中的 &y=2 会被外层 URL 当成另一个参数。修复后整个回调地址作为 redirect 的值传输。

诊断步骤

1. 拆出 scheme、host、path、query 和 fragment。
2. 列出每个 query key 与 value。
3. 只对 value 做组件级编码，尤其是嵌套 URL、中文和保留字符。
4. 用 URL 工具 解码一次，确认得到预期原文。
5. 用 文本对比 比较修复前后结构字符是否只出现在正确层级。

查询参数编码的核心是保护“值的边界”。当值里本身含有 URL 结构字符时，不编码就会破坏外层 URL 的结构。

常见错误表

常见误判

• 把整条 URL 粘贴进组件编码器后直接使用。
• 只编码中文，忽略斜杠、问号和井号。
• 在字符串拼接中手写 &，没有使用 URLSearchParams。
• 重复解码导致百分号序列被破坏。

OAuth、支付回调和广告追踪链接通常对 redirect_uri、click id 和签名参数非常敏感。排查时要保存原始链接，不要只保存浏览器地址栏最终结果。

隐私、安全和适用边界

用于排查时请使用脱敏样本。不要粘贴访问令牌、Cookie、客户资料、内部域名、未公开商业规则、支付记录或完整生产日志。页面适合处理公开示例、教学片段、复现样本和已经替换真实值的配置。

不要公开带真实 token、广告点击 ID、订单号或内部回调地址的完整 URL。可以用 example.com 和占位参数复现编码问题。

复制或发布前复核清单

1. 是否拆分出每个 query key/value。
2. 是否只编码需要作为值的部分。
3. 嵌套 URL 是否整体作为参数值编码。
4. 是否检查重复编码和重复解码。
5. 是否保留原始 URL 与修复 URL。
6. 是否在目标平台重新验证回调或跳转。

相关工具和延伸阅读

参考依据

• WHATWG URL Standard：URL 结构和解析规则。
• MDN URLSearchParams：安全构造查询参数。
• MDN encodeURIComponent()：组件级编码。

编辑记录：Ymir Tool editorial review，2026-06-01。本页作为 Sprint 3 新增案例/排错内容发布，目标是把单一工具入口扩展为可复核的任务说明、错误示例和操作边界。