JavaScript 中的 URL 编码 — encodeURI、encodeURIComponent 与最佳实践

JavaScript 为 URL 编码提供了两个内置函数：encodeURIComponent() 和 encodeURI()。虽然它们的命名相似，功能也看似相近，但使用错误的函数是 Web 开发中最常见的 Bug 之一。本文详细介绍两者的区别、应用场景、常见错误和最佳实践。

encodeURIComponent() 详解

encodeURIComponent() 是最彻底的编码函数。它会编码除了以下字符之外的所有内容：A-Z a-z 0-9 - _ . ! ~ * ' ( )。这意味着它会将 /、?、&、= 等 URL 结构字符也统统编码，因此只适合编码 URL 中的单个组件，例如查询参数的值或是路径中的某一段。

const name = '张三'
const query = '?name=' + encodeURIComponent(name)
// ?name=%E5%BC%A0%E4%B8%89

常见的用法还包括编码表单数据、构建安全的查询字符串、在 AJAX 请求中传递复杂参数。使用我们的免费 URL 编解码工具可以在线验证 encodeURIComponent 的编码结果。

encodeURI() 详解

encodeURI() 的编码范围比 encodeURIComponent() 更窄。它保留了 URL 中具有结构意义的保留字符：:、/、?、#、[、]、@、!、$、&、'、(、)、*、+、,、; 和 =。这意味着它不会破坏 URL 的结构，适合对整个 URL 字符串进行编码。

const url = 'https://example.com/search?q=你好世界'
const encoded = encodeURI(url)
// https://example.com/search?q=%E4%BD%A0%E5%A5%BD%E4%B8%96%E7%95%8C

最常见的陷阱

在 JavaScript 开发中，最常见也最容易出错的操作就是将 encodeURIComponent() 用在了本应使用 encodeURI() 的场景，反之亦然。以下是一个经典的反面案例：

// 错误 — 用 encodeURIComponent 编码完整 URL，破坏了 URL 结构
encodeURIComponent('https://example.com/page?name=张三')
// https%3A%2F%2Fexample.com%2Fpage%3Fname%3D%E5%BC%A0%E4%B8%89
// 这样的结果已经不是一个合法的 URL 了

// 正确 — 用 encodeURI 编码完整 URL，保留结构
encodeURI('https://example.com/page?name=张三')
// https://example.com/page?name=%E5%BC%A0%E4%B8%89

另一个常见的错误是在构建查询字符串时使用 encodeURI() 来编码参数值，导致特殊字符未正确编码，从而引发安全问题或数据丢失。使用我们的 URL 编解码工具可以直观地对比这两种模式的差异。

构建安全的查询字符串

手动拼接查询字符串是最容易出错的编码方式。推荐的做法是使用 URLSearchParams API 来构建查询参数，它会自动处理所有编码细节：

const params = new URLSearchParams()
params.append('q', '你好世界')
params.append('lang', 'zh-CN')
params.append('page', '1')
console.log(params.toString())
// q=%E4%BD%A0%E5%A5%BD%E4%B8%96%E7%95%8C&lang=zh-CN&page=1

URLSearchParams 在内部自动使用 encodeURIComponent() 对值进行编码，所以你不需要手动处理编码细节。在多数现代 JavaScript 项目中，这是构建查询字符串的首选方式。

解码函数：decodeURIComponent 和 decodeURI

与编码函数对应，JavaScript 也提供了两个解码函数。decodeURIComponent() 用于解码由 encodeURIComponent() 编码的字符串，decodeURI() 用于解码由 encodeURI() 编码的字符串。需要注意的是，如果尝试使用 decodeURIComponent() 解码一个不完整的百分号序列（如 %E4 后面缺少足够的十六进制字符），会直接抛出 URIError 异常。因此在实际开发中建议对解码操作进行 try-catch 包裹。

try {
  const decoded = decodeURIComponent('%E4%BD%A0%E5%A5%BD')
  console.log(decoded) // 你好
} catch (e) {
  console.error('解码失败：', e.message)
}

Node.js 中的 URL 编码

在 Node.js 环境中，除了内置的 encodeURI 和 encodeURIComponent 外，还可以使用 querystring 模块的 escape() 和 unescape() 方法。不过从 Node.js 的版本演进来看，querystring 模块正在被 URLSearchParams（通过全局 URL 类提供）所取代。推荐的现代做法是在 Node.js 中同样使用 URL 和 URLSearchParams API，这样前后端代码风格可以保持一致。

处理中文等非 ASCII 字符

对中文等非 ASCII 字符进行编码时，JavaScript 的 encodeURIComponent() 会自动使用 UTF-8 编码。一个中文字符通常占用 3 个字节，编码后会变成 9 个字符（%XX%XX%XX）。例如 你好 经过 encodeURIComponent() 编码后变为 %E4%BD%A0%E5%A5%BD。这个过程对开发者是透明的，你不需要手动处理字节级别的编码细节。

跨语言的一致性

URL 编码是跨语言的通用标准，JavaScript 的编码结果与 Python 的 urllib.parse.quote()、PHP 的 rawurlencode()、Java 的 java.net.URLEncoder.encode() 等产生的输出在底层原理上是一致的。但在具体细节上可能有微妙差异。例如，JavaScript 的 encodeURIComponent 不会编码 ! ' ( ) * - . _ ~，而某些其他语言的对应函数可能会编码其中部分字符。在进行跨语言的数据传递时，建议使用我们的 URL 编解码工具来验证不同语言编码结果的一致性。

最佳实践总结

第一，永远用 encodeURIComponent() 编码查询参数值，用完后再用 encodeURI() 或模板字符串拼接完整 URL。第二，优先使用 URLSearchParams 而非手动拼接查询字符串。第三，在编码完整 URL 时使用 encodeURI()，注意它不会编码查询参数值的内部特殊字符。第四，对解码操作进行异常处理，防止非法的编码字符串导致程序崩溃。第五，在客户端和服务器端都进行 URL 验证和编码，实现深度防御。