企业官网建设流程全解析

es-toolkit 兼容版 escape：HTML 特殊字符转义与 XSS 防护实战指南

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

escape是 es-toolkit 提供的 HTML 特殊字符转义函数，用于将字符串中的&、<、>、"、'转换为对应的 HTML 实体（如<→<），是安全地将用户输入插入 HTML 文档、防范 XSS 攻击的基础工具。本文以 docs/compat/reference/string/escape.md 为骨架，结合源码实现与测试用例，带你掌握兼容版escape的完整用法、非字符串输入处理规则，以及与 es-toolkit 原生版、lodash_.escape的差异与选型建议。

一、函数定位：兼容 lodash 的escape

escape是 es-toolkit 兼容 lodash API 的compat模块成员，可从es-toolkit/compat子路径导入：

import { escape } from 'es-toolkit/compat';

它的核心职责是：将字符串中的 HTML 特殊字符&、<、>、"、'分别转换为对应的 HTML 实体，从而避免这些字符被浏览器解释为标签、属性或实体结构。这一能力在将文本渲染到 HTML 文档时至关重要——例如用户提交的评论、搜索关键词等不可信内容，若不转义直接拼接进 DOM，就可能被注入脚本触发 XSS 攻击。

与其他版本的差异速览

官方文档明确指出：由于需要处理非字符串输入值，兼容版escape运行较慢。如果你只处理字符串，请改用 es-toolkit 原生版 escape，它更快更现代。

二、基础用法与转义规则

函数签名

const result = escape(str);

参数：str（string，可选）——需要转义 HTML 特殊字符的字符串。

返回值：string——特殊字符已被替换为 HTML 实体的字符串。

五种特殊字符的映射关系

兼容版escape转义且仅转义以下 5 个字符，映射表与 lodash 完全一致（见 src/string/escape.ts 中的htmlEscapes常量）：

代码示例

import { escape } from 'es-toolkit/compat'; escape('This is a <div> element.'); // 'This is a &lt;div&gt; element.' escape('This is a "quote"'); // 'This is a &quot;quote&quot;' escape("This is a 'quote'"); // 'This is a &#39;quote&#39;' escape('This is a & symbol'); // 'This is a &amp; symbol'

不会被转义的字符

需要注意，与某些框架的全量转义策略不同，escape只处理上述 5 个字符。测试用例（见 src/string/escape.spec.ts）专门验证了反引号`和正斜杠/不会被转义：

['`', '/'].forEach(chr => { expect(escape(chr)).toBe(chr); // 反引号和斜杠原样返回 });

这一点与 lodash 保持一致，避免对 URL 路径中的/或模板字符串中的`产生意外的破坏性替换。

三、非字符串输入处理：与 lodash 行为对齐的关键

兼容版escape与原生版最大的区别在于对非字符串输入的处理。看源码 src/compat/string/escape.ts 的实现：

export function escape(string?: string): string { return escapeToolkit(toString(string)); }

它先把输入交给 src/compat/util/toString.ts 的toString统一转成字符串，再调用原生escapeToolkit执行实体替换。toString的行为完全复刻 lodash：

• null/undefined→ 返回空字符串''；
• 数字→ 转为数字字符串（如123→'123'）；
• -0→ 保留符号，返回'-0'；
• 数组→ 逐元素拼接，元素间以,分隔（稀疏数组的孔洞按undefined处理）；
• Symbol→ 调用其toString()。

因此文档中的示例可以成立：

import { escape } from 'es-toolkit/compat'; escape(123); // '123' escape(null); // '' escape(undefined); // ''

对应测试见 src/compat/string/escape.spec.ts，其中escape(undefined)被断言返回''。而原生版escape直接对str调用replace，若传入null/undefined会抛出 TypeError，这正是官方建议“处理字符串时用原生版、需要 lodash 兼容行为时用 compat 版”的原因。

四、源码级原理：一次正则替换完成转义

原生版escape的实现极其精简（见 src/string/escape.ts）：

export function escape(str: string): string { return str.replace(/[&<>"']/g, match => htmlEscapes[match]); }

核心机制只有一条正则/[&<>"']/g：

• 字符类[&<>"']：一次性匹配 5 个特殊字符中的任意一个；
• 全局标志g：替换字符串中所有出现的位置，而非只替换第一个；
• 回调函数match => htmlEscapes[match]：把命中的字符作为键，从htmlEscapes映射表中取出对应的 HTML 实体。

由于映射表是普通的对象字面量，查表操作是 O(1)，整个转义过程只需一次线性扫描，性能优于逐个字符判断的循环实现。兼容版在此基础上只多做了一次toString的字符串化前置处理。

与unescape的互逆关系

es-toolkit 同时提供了反向操作 unescape。测试用例验证了两者的互逆性（见 src/string/escape.spec.ts）：

it('should escape the same characters unescaped by `_.unescape`', () => { expect(escape(unescape(escaped))).toBe(escaped); });

即escape(unescape(x)) === x：先反转义再转义，结果不变。这在“从 HTML 提取文本后再安全地渲染回 HTML”的双向流程中非常有用。

五、实战建议与安全注意事项

1. 什么时候用 compat 版，什么时候用原生版

• 纯字符串场景：优先使用import { escape } from 'es-toolkit'的原生版，更快、体积更小；
• 需要对齐 lodash 行为（如处理任意类型输入）的场景：使用import { escape } from 'es-toolkit/compat'，例如从 lodash 迁移且代码中依赖_.escape(null)返回''这类边界行为。

2. 与手动替换的区别

不要手写str.replace(/</g, '&lt;')式的多次替换，原因有二：一是多次replace会产生多遍扫描，性能更差；二是顺序处理容易出错（例如先替换&之外的字符再替换&，会导致实体中的&被二次转义）。escape用单次全局正则加查表的方式，一次遍历完成全部替换，且不会出现二次转义问题。

3. 转义 ≠ 完整 XSS 防护

escape只解决插入 HTML 内容时的特殊字符转义。在实际应用中还需要注意：

• 使用场景：适用于文本节点和属性值的插入；对于插入href、src等 URL 属性，还需要额外的 URL 校验（如过滤javascript:协议）；
• 上下文感知：不同上下文（HTML、属性、URL、CSS、JS）需要不同的编码策略，escape只覆盖 HTML 字符实体这一层；
• 现代框架：React、Vue 等框架在默认插值语法中已内置转义机制，escape更多用于原生 DOM 操作、模板字符串拼接或服务端渲染等需要手动控制输出的场景。

4. 常用调用链

// 场景：把用户输入安全地插入页面 import { escape } from 'es-toolkit/compat'; const userInput = '<script>alert("xss")</script>'; const safeHtml = `<p>${escape(userInput)}</p>`; // 渲染结果：<p>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</p>

六、相关文档与源码索引

• 本函数官方文档：docs/compat/reference/string/escape.md
• 原生版（推荐）文档：docs/reference/string/escape.md
• 兼容版实现：src/compat/string/escape.ts
• 原生版实现与字符映射表：src/string/escape.ts
• 非字符串转换逻辑：src/compat/util/toString.ts
• 兼容版测试：src/compat/string/escape.spec.ts
• 原生版测试：src/string/escape.spec.ts

通过本文，你已经掌握了escape的转义规则、非字符串输入处理机制、底层实现原理与选型策略，可以在项目中安全、高效地处理 HTML 文本输出。

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit