URL Encoding / Percent Encoding

URL 编码与最佳实践

编码与解码

在输入框中粘贴需要处理的文本或 URL，选择「编码」或「解码」操作：

• 编码：将特殊字符转换为 %XX 形式的百分号编码，使其可以安全地放在 URL 中传输
• 解码：将 %XX 形式的编码还原为可读字符

输入后结果会实时更新，可以直接复制使用。

encodeURI 与 encodeURIComponent 的区别

这是日常开发中最容易混淆的两个函数：

• encodeURI：用于编码完整的 URL。它会保留 URL 中的结构性字符，如 :、/、?、#、&、= 等不会被编码
• encodeURIComponent：用于编码 URL 中的某个参数值。它会编码几乎所有特殊字符，包括 &、=、/ 等

举个例子：

原始 URL：https://example.com/search?q=你好&lang=zh

encodeURI 结果：
https://example.com/search?q=%E4%BD%A0%E5%A5%BD&lang=zh
→ URL 结构保持完整，只有中文被编码

encodeURIComponent 结果：
https%3A%2F%2Fexample.com%2Fsearch%3Fq%3D%E4%BD%A0%E5%A5%BD%26lang%3Dzh
→ 整个字符串被编码，URL 结构也被破坏了

经验法则：编码整个 URL 用 encodeURI；编码查询参数的值用 encodeURIComponent。

处理中文和特殊字符

中文字符在 URL 编码时会被转换为 UTF-8 字节序列。例如「你」的 UTF-8 编码是 E4 BD A0，对应的 URL 编码就是 %E4%BD%A0。

常见的需要编码的特殊字符：

避免双重编码

双重编码是最常见的坑。如果一个字符串已经被编码过一次，再编码一次就会把 % 也编码为 %25，导致：

原始：你好
第一次编码：%E4%BD%A0%E5%A5%BD（正确）
第二次编码：%25E4%25BD%25A0%25E5%25A5%25BD（错误）

解码时也要注意：如果发现解码结果中仍然有 %XX 形式的内容，说明原始数据被多次编码了，需要再解码一次。

在工具中，你可以反复点击解码按钮，直到结果不再变化为止。

API

可注意各语言 API 对于保留字符 ! ( 等的处理

Javascript

// => '%E5%B1%B1%E6%9C%88'
encodeURIComponent('山月')

// => '山月'
decodeURIComponent('%E5%B1%B1%E6%9C%88')

// => '(!'
encodeURIComponent('(!')

Python

from urllib.parse import quote, unquote

# => '%E5%B1%B1%E6%9C%88'
quote('山月')

# => '山月'
unquote('%E5%B1%B1%E6%9C%88')

# => '%3F%21'
quote('?!')

常见问题

Q: encodeURI 和 encodeURIComponent 有什么区别？

encodeURI 用于编码完整的 URI，它不会编码 URI 中有特殊含义的字符，如 :、/、?、#、&、= 等。encodeURIComponent 则用于编码 URI 的某个组成部分（如查询参数的值），它会编码几乎所有特殊字符。例如，对 https://example.com/搜索?q=你好 使用 encodeURI 只会编码中文部分，而使用 encodeURIComponent 则连 ://、/、?、= 都会被编码。因此在拼接查询参数时应使用 encodeURIComponent。

Q: 为什么中文在 URL 中会变成 %XX 格式？

URL 规范（RFC 3986）规定 URI 中只能包含 ASCII 字符集中的一部分安全字符。中文字符不在允许范围内，所以必须经过编码才能在 URL 中传输。编码过程是先将中文字符按 UTF-8 编码为字节序列，然后将每个字节表示为 % 加两位十六进制数的形式。例如「你」的 UTF-8 编码为 E4 BD A0，在 URL 中就表示为 %E4%BD%A0。

Q: URL 编码和 Base64 编码有什么区别？

两者用途完全不同。URL 编码（Percent-Encoding）专门用于在 URL 中安全传输特殊字符和非 ASCII 字符，编码后的结果仍然是可读的（未编码部分保持原样）。Base64 编码则是将任意二进制数据转换为纯 ASCII 文本，常用于在文本协议（如 JSON、XML、邮件）中嵌入二进制内容。Base64 会对所有数据进行转换，输出结果不保留原始可读性。两者也可以组合使用，比如将 Base64 结果放入 URL 参数时，可能需要再做一次 URL 编码。

Q: 什么是双重编码？如何避免？

双重编码是指对已经编码过的字符串再次进行编码，导致 % 本身被编码为 %25。例如「你好」第一次编码为 %E4%BD%A0%E5%A5%BD，如果再次编码就会变成 %25E4%25BD%25A0%25E5%25A5%25BD，服务端解码一次后得到的是编码字符串而非原始内容。双重编码通常发生在多层框架或中间件各自执行编码操作时。避免的方法是明确编码职责：只在最终拼接 URL 时编码一次，不要在数据传递的中间环节编码。

Q: 空格在 URL 中应该编码为 %20 还是 +？

两种方式都有使用，但适用场景不同。在 URL 路径和通用 URI 组件中，空格应编码为 %20，这是 RFC 3986 的标准。而在 application/x-www-form-urlencoded 格式中（即 HTML 表单提交的默认格式），空格会被编码为 +，这是历史约定。JavaScript 中 encodeURIComponent 将空格编码为 %20，而 URLSearchParams 则将空格编码为 +。在大多数场景下两者都能被正确解码，但为了规范性，建议在非表单场景使用 %20。