异常教程

JavaScript encodeURI() 函数（一文讲透）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战(已更新的所有项目都能学习) / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新开坑项目:《Spring AI 项目实战》 正在持续爆肝中，基于 Spring AI + Spring Boot 3.x + JDK 21...， 点击查看 ;
  • 《从零手撸：仿小红书（微服务架构）》 已完结，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 100w+ 字，讲解图 4013+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3700+ 小伙伴加入学习 ，欢迎点击围观

在现代 Web 开发中，处理 URL 参数和特殊字符是一个常见需求。无论是构建表单提交、API 请求，还是动态生成页面链接，开发者都可能遇到因特殊字符导致的 URL 解析问题。此时，JavaScript 的 encodeURI() 函数便成为了解决此类问题的关键工具。本文将从基础概念到实际应用，逐步解析这一函数的功能、使用场景及注意事项，帮助开发者避免编码陷阱，提升代码的健壮性。

一、URL 编码的基本原理

1.1 为什么需要 URL 编码？

想象一个场景：用户输入的姓名包含空格或特殊符号（如 @、#），若直接拼接到 URL 中，浏览器可能会将这些字符误解为路径分隔符或参数标识符，导致请求失败。例如，用户输入 "张三@公司"，直接拼接成 https://example.com/search?user=张三@公司 时，@ 和 公司 后的部分可能被解析为邮箱地址或路径的一部分，而非原始文本。

URL 编码的作用正是将这些特殊字符转换为浏览器可识别的十六进制编码（如 %20 表示空格），确保 URL 的完整性和有效性。

1.2 URL 编码的核心规则

URL 编码遵循以下规则：

  1. 保留字符：A-Z、a-z、0-9、-、.、_、~ 可直接使用，无需编码。
  2. 需编码字符：所有其他字符（如中文、空格、#、& 等）均需转换为 %HH 格式，其中 HH 是字符的 ASCII 码的十六进制表示。
  3. 特殊保留字符：?、/、:、@ 等在 URL 结构中具有特定含义的字符，需根据使用场景决定是否编码。

例如，字符串 "中文/空格@#" 经编码后会变成 %E4%B8%AD%E6%96%87%2F%E7%A9%BA%E6%A0%BC%40%23。

二、encodeURI() 函数详解

2.1 函数定义与基本用法

encodeURI() 是 JavaScript 内置的全局函数，用于对完整的 URL 字符串进行编码。其语法如下：

encodeURI(uri);

其中 uri 是需要编码的原始 URL 字符串。函数返回编码后的字符串。

示例 1：基础编码

const originalUrl = "https://example.com/search?query=张三@公司";
const encodedUrl = encodeURI(originalUrl);
console.log(encodedUrl);
// 输出：https://example.com/search?query=%E5%BC%A0%E4%B8%89%40%E5%85%AC%E5%8F%B8

2.2 编码规则与例外情况

encodeURI() 的编码规则有两点关键特性：

  1. 保留特殊保留字符：#、/、?、:、;、=、& 等字符会被保留，因为它们在 URL 的路径、查询参数或片段标识中具有特定意义。
  2. 编码其他特殊字符：如空格会被转为 %20，中文字符会被转为对应的 Unicode 编码。

示例 2：保留与编码对比

const testString = "https://example.com/path?param=空格@#";
console.log(encodeURI(testString));
// 输出：https://example.com/path?param=%E7%A9%BA%E6%A0%BC%40%23
// 其中：
// 空格 → %20（但此处未出现，因原字符串中使用的是“空格”二字）
// @ → %40
// # → %23（但 # 在 URL 中通常用于片段标识符，需谨慎编码）

三、encodeURI() 与 encodeURIComponent() 的区别

开发者常混淆这两个函数，但它们的核心区别在于：
| 函数名 | 适用场景 | 编码规则差异 | |-----------------------|-----------------------------------|----------------------------------| | encodeURI() | 编码完整的 URL 字符串 | 保留 #、/、? 等特殊字符 | | encodeURIComponent() | 编码 URL 的单个组件（如参数值） | 编码所有非保留字符，包括 # 等 |

示例 3：函数对比案例

const paramValue = "张三@公司#部门";
// 使用 encodeURI()
console.log(encodeURI(paramValue));
// 输出：张三%40公司%23部门（保留了 @ 和 # 的原始编码）

// 使用 encodeURIComponent()
console.log(encodeURIComponent(paramValue));
// 输出：%E5%BC%A0%E4%B8%89%40%E5%85%AC%E5%8F%B8%23%E9%83%A8%E9%97%A8（所有特殊字符均被编码）

关键区别总结：

  • 若需编码整个 URL，使用 encodeURI()；
  • 若需编码 URL 的某个具体部分（如查询参数值），应使用 encodeURIComponent()，以避免保留字符引发的逻辑错误。

四、常见使用场景与案例

4.1 场景 1：动态构建带参数的 URL

function buildSearchUrl(query, page) {
  const base = "https://api.example.com/search?";
  const encodedQuery = encodeURIComponent(query);
  const encodedPage = encodeURIComponent(page);
  return `${base}q=${encodedQuery}&page=${encodedPage}`;
}

// 使用示例
const url = buildSearchUrl("张三@公司", "第2页");
console.log(url);
// 输出：https://api.example.com/search?q=%E5%BC%A0%E4%B8%89%40%E5%85%AC%E5%8F%B8&page=%E7%AC%AC2%E9%A1%B5

4.2 场景 2：处理用户输入的特殊字符

当用户输入包含 %、+ 等符号时，需确保编码后的 URL 正确传递原始值：

const userInput = "搜索%20测试+关键词";
const encodedInput = encodeURIComponent(userInput);
console.log(encodedInput);
// 输出：%E6%90%9C%E7%B4%A2%2520%E6%B5%8B%E8%AF%95%2B%E5%85%B3%E9%94%AE%E8%AF%8D
// 解析后，服务端可正确还原原始输入

五、常见问题与解决方案

5.1 问题 1：编码后 URL 仍无法解析

原因：可能因未对 URL 的各个组件进行独立编码。例如，直接拼接参数值：

const param = "name=李四&age=25"; // 含 & 符号未编码
const url = "https://api.example.com?params=" + param;
// 错误编码结果：https://api.example.com?params=name=李四&age=25
// 导致参数解析为 name=李四 和 age=25，而非预期的 params 参数值

解决方案：使用 encodeURIComponent() 对参数值编码：

const encodedParam = encodeURIComponent("name=李四&age=25");
const correctUrl = `https://api.example.com?params=${encodedParam}`;
// 输出：https://api.example.com?params=name%3D%E6%9D%8E%E5%9B%9B%26age%3D25

5.2 问题 2：中文字符编码后出现乱码

原因：通常因服务端未正确解析编码后的 Unicode 字符。例如，某些后端语言默认使用 ISO-8859-1 编码而非 UTF-8。

解决方案：

  1. 确保服务端以 UTF-8 解析 URL 参数；
  2. 在编码前将字符串转换为 UTF-8 编码（现代浏览器通常已支持，但可通过 TextEncoder 显式处理）：
const textEncoder = new TextEncoder();
const utf8Bytes = textEncoder.encode("中文测试");
const encodedUtf8 = encodeURIComponent(new TextDecoder().decode(utf8Bytes));
// 确保编码后的字节流与服务端解码方式一致

六、进阶技巧与最佳实践

6.1 使用正则表达式辅助编码验证

对于复杂场景，可结合正则表达式验证编码结果是否符合预期：

function isValidEncodedUrl(encodedUrl) {
  // 简单验证是否包含非法字符（如未编码的 #）
  const invalidChars = /[\s!"$&'()*+,/:;=?@]/g;
  return !invalidChars.test(encodedUrl);
}

6.2 与 decodeURI() 配套使用

在服务端或客户端解码时，需对应使用 decodeURI() 或 decodeURIComponent()：

const encoded = encodeURI("https://example.com/路径/测试");
console.log(decodeURI(encoded));
// 输出：https://example.com/路径/测试

结论

JavaScript encodeURI() 函数是处理 URL 编码的核心工具，其通过保留关键字符与编码特殊符号的机制，确保了 URL 的结构完整性。开发者需根据具体场景选择 encodeURI() 或 encodeURIComponent()，并在编码前后进行验证，以避免因字符解析错误导致的 Bug。掌握这一函数的深层逻辑与最佳实践，将显著提升代码的健壮性与跨平台兼容性。

通过本文的示例与分析，读者应能快速上手 URL 编码的实现，并在实际项目中灵活应用这一技术，解决开发中的编码难题。

最新发布

查看更多文章