encodeURI 与 encodeURIComponent 区别

这个页面解决什么问题

encodeURI 和 encodeURIComponent 的名字相似，但使用边界不同。encodeURI 适合处理已经是完整 URL 的字符串，会保留 :、/、?、& 等结构字符；encodeURIComponent 适合处理 URL 的一个组件，尤其是 query value，会编码这些结构字符。

选错函数会造成两类故障：完整 URL 的结构被破坏，或者参数值中的结构字符没有被保护。这个页面用最小例子说明何时保留结构，何时保护值。

快速判断

• 输入是完整 URL，通常不要用 encodeURIComponent 整体处理。
• 输入是 query 参数值，通常不要只用 encodeURI。
• 值中包含 &、=、? 时，需要组件编码。
• 现代代码构造 query 时优先使用 URLSearchParams，减少手写拼接。

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

坏样例用 encodeURI 编码参数值，导致内部 & 没有被保护。

encodeURI("a=1&b=2") -> a=1&b=2

encodeURIComponent("a=1&b=2") -> a%3D1%26b%3D2

如果这个字符串是参数值，& 应保留为值的一部分，而不是变成外层参数分隔符。

诊断步骤

1. 写下输入在 URL 中的位置：完整 URL、path、query key、query value 或 fragment。
2. 完整 URL 需要保留结构字符，组件值需要编码结构字符。
3. 对比 encodeURI 和 encodeURIComponent 的输出。
4. 如果代码中手写拼接 query，改用 URLSearchParams 或明确组件编码。
5. 在浏览器和服务端分别打印解析后的参数，确认值没有被拆分。

函数选择不是风格问题，而是结构边界问题。同一个字符在 path 中可能是分隔符，在 query value 中可能只是普通数据。

常见错误表

常见误判

• 用一个函数处理所有 URL 相关文本。
• 只在前端看地址栏，不看服务端实际收到的参数。
• 把 encodeURI 当成“更少编码所以更安全”。
• 在已经编码的字符串上再次编码。

排查时可以把同一输入分别用两种函数处理，再用文本对比观察保留字符。差异最多的位置，就是需要明确边界的位置。

隐私、安全和适用边界

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

本页不讨论 URL 签名算法。若参数参与签名，编码顺序、排序和大小写必须按平台规范执行，不能手动猜测。

复制或发布前复核清单

1. 输入位置是否明确。
2. 是否知道哪些字符应该保留为结构。
3. query value 是否使用组件编码。
4. 是否避免对完整 URL 整体组件编码。
5. 是否在服务端确认实际参数值。
6. 是否检查签名或白名单要求。

相关工具和延伸阅读

参考依据

• MDN encodeURI()：完整 URI 编码行为。
• MDN encodeURIComponent()：组件编码行为。
• WHATWG URL Standard：URL 组件解析。

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