# jsesc 中文文档

规范地址：https://npmcn.com/package/jsesc/

版本：3\.1\.0
npm 元数据更新时间：2024-12-11T08:24:34.718Z
中文译文更新时间：2026-11-04T16:47:37.344Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/jsesc
原文对照：https://npmcn.com/package/jsesc/?lang=original
项目主页：https://mths.be/jsesc
源码仓库：https://github.com/mathiasbynens/jsesc

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：32.3 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=6
- 运行依赖：0 个
- 首次发布：2013-07-27T09:03:48.064Z
- 最新版本发布：2024-12-11T08:24:34.551Z
- 近 30 天下载量：733527831（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 0 个）

## 中文简介

给定一些数据，jsesc返回该数据的最短字符串化和ascii安全表示形式。

## 安装

```sh
npm install jsesc
```

也可以使用：`pnpm add jsesc`、`yarn add jsesc`、`bun add jsesc`

## README

# jsesc

给定一些数据， _jsesc_ 返回该数据的字符串化表示形式。耶稣类似于 `JSON.stringify()` 除了:

1.  它输出JavaScript而不是JSON [默认情况下](https://npmcn.com/package/jsesc/#readme-json)支持ES6地图和集合等数据结构；
2.  它提供了 [许多选项](https://npmcn.com/package/jsesc/#readme-api) 自定义输出；
3.  它的输出是ascii安全的 [默认情况下](https://npmcn.com/package/jsesc/#readme-minimal)，这要归功于它的用法 [转义序列](https://mathiasbynens.be/notes/javascript-escapes) 在需要的地方。

对于任何输入，jsesc生成尽可能短的有效的仅限可打印ascii的输出。 [这是一个在线演示。](https://mothereff.in/js-escapes)

可以使用Jsesc的输出来代替 `JSON.stringify`要避免的 [mojibake](https://en.wikipedia.org/wiki/Mojibake) 和其他编码问题，甚至 [避免错误](https://twitter.com/annevk/status/380000829643571200) 当传递json格式的数据时(可能包含U+2028 LINE SEPARATOR， U+2029 PARAGRAPH SEPARATOR，或 [孤独的代理人](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14))到JavaScript解析器或UTF-8编码器。

## 安装

通过 [npm](https://www.npmjs.com/)：

```bash
npm install jsesc
```

在 [node . js](https://nodejs.org/)：

```js
const jsesc = require('jsesc');
```

## API

### `jsesc(value, options)`

此函数接受一个值并返回该值的转义版本，其中任何不可打印的ASCII符号都使用尽可能短的（但有效的）转义。 [用于JavaScript字符串的转义序列](https://mathiasbynens.be/notes/javascript-escapes)。第一个支持的值类型是字符串：

```js
jsesc('Ich ♥ Bücher');
// → 'Ich \\u2665 B\\xFCcher'

jsesc('foo 𝌆 bar');
// → 'foo \\uD834\\uDF06 bar'
```

不是字符串，而是 `value` 也可以是数组、对象、映射、集合或缓冲区。在这种情况下， `jsesc` 返回值的字符串化版本，其中非可打印ASCII符号的任何字符都以相同的方式转义。

```js
// Escaping an array
jsesc([
  'Ich ♥ Bücher', 'foo 𝌆 bar'
]);
// → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'

// Escaping an object
jsesc({
  'Ich ♥ Bücher': 'foo 𝌆 bar'
});
// → '{\'Ich \\u2665 B\\xFCcher\':\'foo \\uD834\\uDF06 bar\'}'
```

可选 `options` 参数接受一个具有以下选项的对象：

#### `quotes`

的默认值 `quotes` 选择是 `'single'`。这意味着任何发生 `'` 在输入字符串中被转义为 `\'`，以便输出可以在用单引号包装的字符串文本中使用。

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.');
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'

jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single'
});
// → '`Lorem` ipsum "dolor" sit \\\'amet\\\' etc.'
// → "`Lorem` ipsum \"dolor\" sit \\'amet\\' etc."
```

如果您希望将输出作为用双引号括起来的字符串文本的一部分，请设置 `quotes` 选项 `'double'`。

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double'
});
// → '`Lorem` ipsum \\"dolor\\" sit \'amet\' etc.'
// → "`Lorem` ipsum \\\"dolor\\\" sit 'amet' etc."
```

如果你想使用输出作为模板文字的一部分（即用反引号括起来），设置 `quotes` 选项 `'backtick'`。

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'backtick'
});
// → '\\`Lorem\\` ipsum "dolor" sit \'amet\' etc.'
// → "\\`Lorem\\` ipsum \"dolor\" sit 'amet' etc."
// → `\\\`Lorem\\\` ipsum "dolor" sit 'amet' etc.`
```

这个设置也会影响数组和对象的输出：

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'quotes': 'double'
});
// → '{"Ich \\u2665 B\\xFCcher":"foo \\uD834\\uDF06 bar"}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'quotes': 'double'
});
// → '["Ich \\u2665 B\\xFCcher","foo \\uD834\\uDF06 bar"]'
```

#### `numbers`

的默认值 `numbers` 选择是 `'decimal'`。这意味着任何数值都使用十进制整数字面值表示。其他有效的选项包括 `binary`， `octal`, `hexadecimal`，分别产生二进制整数字面值、八进制整数字面值和十六进制整数字面值。

```js
jsesc(42, {
  'numbers': 'binary'
});
// → '0b101010'

jsesc(42, {
  'numbers': 'octal'
});
// → '0o52'

jsesc(42, {
  'numbers': 'decimal'
});
// → '42'

jsesc(42, {
  'numbers': 'hexadecimal'
});
// → '0x2A'
```

#### `wrap`

这个 `wrap` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。启用后，输出是用引号括起来的有效JavaScript字符串。参数指定引号的类型 `quotes` 设置。

```js
jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single',
  'wrap': true
});
// → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
// → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"

jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double',
  'wrap': true
});
// → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
// → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""
```

#### `es6`

这个 `es6` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。启用后，输入中的任何星形Unicode符号都将使用 [ECMAScript 6 Unicode码点转义序列](https://mathiasbynens.be/notes/javascript-escapes#unicode-code-point) 而不是为每个代理部分使用单独的转义序列。如果您担心与ES5环境的向后兼容性，请不要启用此设置。如果 `json` 设置为启用时，值为 `es6` 设置被忽略（就像它被忽略一样） `false`）.

```js
// By default, the `es6` option is disabled:
jsesc('foo 𝌆 bar 💩 baz');
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To explicitly disable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': false
});
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To enable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': true
});
// → 'foo \\u{1D306} bar \\u{1F4A9} baz'
```

#### `escapeEverything`

这个 `escapeEverything` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。启用后，输出中的所有符号都被转义——甚至包括可打印的ASCII符号。

```js
jsesc('lolwat"foo\'bar', {
  'escapeEverything': true
});
// → '\\x6C\\x6F\\x6C\\x77\\x61\\x74\\"\\x66\\x6F\\x6F\\\'\\x62\\x61\\x72'
// → "\\x6C\\x6F\\x6C\\x77\\x61\\x74\\\"\\x66\\x6F\\x6F\\'\\x62\\x61\\x72"
```

此设置还会影响数组和对象中字符串字面值的输出。

#### `minimal`

这个 `minimal` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。当启用时，输出中只有一组有限的符号被转义：

-   U + 0000 `\0`
-   U + 0008 `\b`
-   U + 0009 `\t`
-   U + 000 `\n`
-   U + 000 c `\f`
-   U + 000 d `\r`
-   U + 005 c `\\`
-   U + 2028 `\u2028`
-   U + 2029 `\u2029`
-   用于包装字符串字面值的任何符号(基于 [这个 `quotes` 选项](https://npmcn.com/package/jsesc/#readme-quotes)）
-   [孤独的代理人](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)

注意：启用此选项后，jsesc输出不再保证是ascii安全的。

```js
jsesc('foo\u2029bar\nbaz©qux𝌆flops', {
  'minimal': false
});
// → 'foo\\u2029bar\\nbaz©qux𝌆flops'
```

#### `isScriptContext`

这个 `isScriptContext` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。启用后，会出现 [`</script` 和 `</style`](https://mathiasbynens.be/notes/etago) 在输出中被转义为 `<\/script` 和 `<\/style`, [`<!--`](https://mathiasbynens.be/notes/etago#comment-8) 被转义为 `\x3C!--` (或 `\u003C!--` 当 `json` 选项已启用)。当jsesc的输出最终作为a的一部分时，此设置非常有用 `<script>` 或 `<style>` 元素在HTML文档中。

```js
jsesc('foo</script>bar', {
  'isScriptContext': true
});
// → 'foo<\\/script>bar'
```

#### `compact`

这个 `compact` 选项接受布尔值(`true` 或 `false`)，默认为 `true` (使)。启用后，数组和对象的输出尽可能紧凑；格式不太好。

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': true // this is the default
});
// → '{\'Ich \u2665 B\xFCcher\':\'foo \uD834\uDF06 bar\'}'

jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false
});
// → '[\n\t\'Ich \u2665 B\xFCcher\',\n\t\'foo \uD834\uDF06 bar\'\n]'
```

此设置对字符串的输出没有影响。

#### `indent`

这个 `indent` 选项接受字符串值，默认值为 `'\t'`。当 `compact` 设置已禁用(`false`的值 `indent` 选项用于格式化数组和对象的输出。

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '\t' // this is the default
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '  '
});
// → '{\n  \'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false,
  'indent': '  '
});
// → '[\n  \'Ich \u2665 B\xFCcher\',\n\  t\'foo \uD834\uDF06 bar\'\n]'
```

此设置对字符串的输出没有影响。

#### `indentLevel`

这个 `indentLevel` 选项接受一个数值，默认值为 `0`。它表示当前缩进级别，即值的次数 [这个 `indent` 选项](https://npmcn.com/package/jsesc/#readme-indent) 是重复的。

```js
jsesc(['a', 'b', 'c'], {
  'compact': false,
  'indentLevel': 1
});
// → '[\n\t\t\'a\',\n\t\t\'b\',\n\t\t\'c\'\n\t]'

jsesc(['a', 'b', 'c'], {
  'compact': false,
  'indentLevel': 2
});
// → '[\n\t\t\t\'a\',\n\t\t\t\'b\',\n\t\t\t\'c\'\n\t\t]'
```

#### `json`

这个 `json` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。启用后，输出是有效的JSON。 [十六进制字符转义序列](https://mathiasbynens.be/notes/javascript-escapes#hexadecimal) 和 [这个 `\v` 或 `\0` 转义序列](https://mathiasbynens.be/notes/javascript-escapes#single) 不使用。设置 `json: true` 意味着 `quotes: 'double', wrap: true, es6: false`尽管如果需要，仍然可以覆盖这些值——但在这种情况下，输出将不再是有效的JSON。

```js
jsesc('foo\x00bar\xFF\uFFFDbaz', {
  'json': true
});
// → '"foo\\u0000bar\\u00FF\\uFFFDbaz"'

jsesc({ 'foo\x00bar\xFF\uFFFDbaz': 'foo\x00bar\xFF\uFFFDbaz' }, {
  'json': true
});
// → '{"foo\\u0000bar\\u00FF\\uFFFDbaz":"foo\\u0000bar\\u00FF\\uFFFDbaz"}'

jsesc([ 'foo\x00bar\xFF\uFFFDbaz', 'foo\x00bar\xFF\uFFFDbaz' ], {
  'json': true
});
// → '["foo\\u0000bar\\u00FF\\uFFFDbaz","foo\\u0000bar\\u00FF\\uFFFDbaz"]'

// Values that are acceptable in JSON but aren’t strings, arrays, or object
// literals can’t be escaped, so they’ll just be preserved:
jsesc([ 'foo\x00bar', [1, '©', { 'foo': true, 'qux': null }], 42 ], {
  'json': true
});
// → '["foo\\u0000bar",[1,"\\u00A9",{"foo":true,"qux":null}],42]'
// Values that aren’t allowed in JSON are run through `JSON.stringify()`:
jsesc([ undefined, -Infinity ], {
  'json': true
});
// → '[null,null]'
```

**注意:** 在包含非字符串值的对象或数组上使用此选项依赖于 `JSON.stringify()`。对于像IE≤7这样的遗留环境，使用 [一个 `JSON` polyfill](http://bestiejs.github.io/json3/)。

#### `lowercaseHex`

这个 `lowercaseHex` 选项接受布尔值(`true` 或 `false`)，默认为 `false` (禁用)。启用后，转义序列中的任何十六进制字母数字以及任何十六进制整数字面值(请参阅 [这个 `numbers` 选项](https://npmcn.com/package/jsesc/#readme-numbers))中的字符都是小写的。

```js
jsesc('Ich ♥ Bücher', {
  'lowercaseHex': true
});
// → 'Ich \\u2665 B\\xfccher'
//                    ^^

jsesc(42, {
  'numbers': 'hexadecimal',
  'lowercaseHex': true
});
// → '0x2a'
//      ^^
```

### `jsesc.version`

表示语义版本号的字符串。

### 使用 `jsesc` 二进制

要使用 `jsesc` 在shell中安装二进制文件，使用npm全局安装jsesc：

```bash
npm install -g jsesc
```

之后你就可以从命令行转义字符串了：

```bash
$ jsesc 'föo ♥ bår 𝌆 baz'
f\xF6o \u2665 b\xE5r \uD834\uDF06 baz
```

要转义包含字符串值的数组或对象，请使用 `-o`/`--object` 选择:

```bash
$ jsesc --object '{ "föo": "♥", "bår": "𝌆 baz" }'
{'f\xF6o':'\u2665','b\xE5r':'\uD834\uDF06 baz'}
```

在这种情况下，要美化输出，请使用 `-p`/`--pretty` 选择:

```bash
$ jsesc --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  'f\xF6o': '\u2665',
  'b\xE5r': '\uD834\uDF06 baz'
}
```

对于有效的JSON输出，使用 `-j`/`--json` 选择:

```bash
$ jsesc --json --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  "f\u00F6o": "\u2665",
  "b\u00E5r": "\uD834\uDF06 baz"
}
```

读取本地JSON文件，转义任何非ascii符号，并将结果保存到新文件：

```bash
$ jsesc --json --object < data-raw.json > data-escaped.json
```

或者对在线JSON文件做同样的事情：

```bash
$ curl -sL "http://git.io/aorKgQ" | jsesc --json --object > data-escaped.json
```

看到 `jsesc --help` 以获取完整的选项列表。

## 支持

从v3.0.0开始，jsesc只支持Node.js v6+。

旧版本（jsesc v1.3.0之前）支持Chrome 27、Firefox 3、Safari 4、Opera 10、IE 6、Node.js v6.0.0、Narwhal 0.3.2、ringgojs 0.8-0.11、PhantomJS 1.9.0和Rhino 1.7RC4。 **注意:** 使用 `json` 对象或数组中包含非字符串值的选项 `JSON.parse()`。对于像IE≤7这样的遗留环境，使用 [一个 `JSON` polyfill](https://bestiejs.github.io/json3/)。

## 作者

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
| --- |
| [马赛厄斯Bynens](https://mathiasbynens.be/) |

## 许可证

这个图书馆可以在 [麻省理工学院](https://mths.be/mit) 许可证。

## 常见问题

### jsesc 是什么？

给定一些数据，jsesc返回该数据的最短字符串化和ascii安全表示形式。

### 如何安装 jsesc？

在项目目录运行 npm install jsesc，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 jsesc，可以用 npx jsesc 直接运行。

### jsesc 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/jsesc 是否存在。

### jsesc 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### jsesc 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=6。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### jsesc 可以商用吗？

jsesc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### jsesc 的下载量有多少？

根据 npm 官方下载统计，jsesc 在 2026/10/05 – 2026/11/03 这 30 天内被下载 733,527,831 次，日均约 24,450,928 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### jsesc 还在维护吗？

最新版本 3\.1\.0 发布于 2024/12/11（1\.9 年前）；至今共发布 23 个版本，其中过去 12 个月发布了 0 个；首次发布于 2013/07/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。