企业官网建设流程全解析

Babel 插件 @babel/plugin-transform-json-strings 详解：转义 JS 字符串中的 U+2028 与 U+2029 分隔符

【免费下载链接】babel🐠 Babel is a compiler for writing next generation JavaScript.项目地址: https://gitcode.com/gh_mirrors/ba/babel

导读

@babel/plugin-transform-json-strings是 Babel 官方插件包之一，核心职责是将 JavaScript 字符串字面量与指令字面量中出现的U+2028 LINE SEPARATOR（行分隔符）与U+2029 PARAGRAPH SEPARATOR（段落分隔符）转义为等价的\u2028/\u2029转义序列。本文以该插件的 README 为骨架，结合 插件源码 与仓库内的测试用例，完整讲解其安装、配置、实现原理、奇偶反斜杠等边界场景，以及它与@babel/preset-env的协作关系。读完本文，你将能够独立安装并在工程中正确配置该插件，并理解其"只重写原始文本、不动 AST 语义"的设计思路。

为什么需要转义 U+2028 / U+2029

在 ECMAScript 2019 之前，JavaScript 规范（ES5/ES2015 等）沿用了 JSON 的字符串定义，规定字符串字面量中不允许出现未经转义的 U+2028（行分隔符）和 U+2029（段落分隔符）。一旦源码中出现这两个字符，旧版 JavaScript 引擎会直接抛出语法错误（SyntaxError），例如把包含这两个字符的字符串粘贴进源码、或由某些工具生成的代码中时，会意外编译失败。

这一约束与 JSON 完全一致——JSON 规范本身也禁止在字符串中出现未转义的这两个字符，因此当时人们常说"JavaScript 是 JSON 的超集"并不完全成立（JSON 中允许它们，而 JS 不允许）。ECMAScript 2019 引入 "JSON superset" 提案，正式允许在 JavaScript 字符串字面量中直接书写 U+2028 / U+2029，使 JS 真正成为 JSON 的超集。@babel/plugin-transform-json-strings正是用于把这种"新语法"降级转译，让包含这两个字符的源码在老引擎上也能正常运行。

插件在 package.json 中的官方描述精炼概括了其功能：

Escape U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in JS strings

安装

按照 README 的说明，使用 npm 以开发依赖方式安装：

npm install --save-dev @babel/plugin-transform-json-strings

或使用 yarn：

yarn add @babel/plugin-transform-json-strings --dev

安装为devDependencies是因为插件仅在构建/转译阶段发挥作用，不会进入运行时依赖。从仓库的 package.json 可以看到，该插件运行时只依赖@babel/helper-plugin-utils，并以@babel/core（^8.0.0）作为 peerDependency，因此请确保项目中已安装兼容版本的@babel/core。

配置与使用

在 Babel 配置中启用插件

安装完成后，在 Babel 配置文件（如babel.config.json）中启用：

{ "plugins": ["@babel/plugin-transform-json-strings"] }

插件本身不接收任何参数，直接以字符串形式列出即可。它既可以作为独立插件使用，也可以作为@babel/preset-env的底层转换组件被间接启用（详见下文"与 preset-env 的协作"）。

命令行使用

使用@babel/cli时，可通过--plugins参数显式指定：

babel input.js --plugins @babel/plugin-transform-json-strings --out-file output.js

转换效果一览

以下面这段包含原始 U+2028 字符的代码为例（测试用例取自 directive-line-separator 输入）：

"before after"; // between 'before' and 'after' 之间是一个 U+2028 LINE SEPARATOR " "; // 单独一个 U+2028 LINE SEPARATOR "\ "; // 已被反斜杠转义的 U+2028 LINE SEPARATOR "\u2028"; // 已是转义序列的 U+2028 LINE SEPARATOR

经插件转换后（对应 output.js）：

"before\u2028after"; "\u2028"; "\ "; // 保持原样：已被转义的字符不再重复转义 "\u2028"; // 保持原样

可以看到：裸的 U+2028 被改写为\u2028，而已经带反斜杠或已是转义序列的形式保持不动。这正是插件最核心的语义保证——绝不改变字符串在运行时的实际值。

实现原理：源码级剖析

插件完整的转换逻辑位于 src/index.ts，全篇不足 30 行，实现非常精巧，值得逐行拆解。

1. 正则匹配：考虑反斜杠前缀

const regex = /(\\*)([\u2028\u2029])/g;

该全局正则捕获两类内容：(\\*)捕获 U+2028/U+2029 之前连续的零个或多个反斜杠；[\u2028\u2029]匹配目标字符本身。之所以要捕获前缀反斜杠，是为了判断该分隔符是否已被转义——这引出了下面的奇偶判断。

2. 奇数反斜杠判断：区分"已转义"与"未转义"

function replace(match: string, escapes: string, separator: string) { // If there's an odd number, that means the separator itself was escaped. // "\X" escapes X. // "\\X" escapes the backslash, so X is unescaped. const isEscaped = escapes.length % 2 === 1; if (isEscaped) return match; return `${escapes}\\u${separator.charCodeAt(0).toString(16)}`; }

这是整个插件最关键的正确性设计，其规则为：

• 奇数个反斜杠（如"\ "）：反斜杠直接作用于分隔符，分隔符本身已被转义，属于合法的"新语法"文本，原样返回；
• 偶数个反斜杠（如"\\ "、"\\\\ "）：反斜杠两两配对转义的是反斜杠本身，紧随其后的 U+2028/U+2029 实际是未被转义的裸字符，需要被改写为\uXXXX，同时保留原有的偶数个反斜杠。

改写后的转义序列通过separator.charCodeAt(0).toString(16)计算：U+2028 →\u2028，U+2029 →\u2029。

3. 只改写原始文本：extra.raw

visitor: api.traverse.explode({ "DirectiveLiteral|StringLiteral"({ node }) { const { extra } = node; if (!extra?.raw) return; extra.raw = (extra.raw as string).replace(regex, replace); }, }),

插件同时监听DirectiveLiteral（指令字面量，如"use strict"及其它字符串指令）和StringLiteral（普通字符串字面量）两种节点。它只修改节点上的extra.raw字段——即源码中的原始字符串文本，而不触碰node.value（运行时语义值）。这是理解本插件设计的关键：

• extra.raw是 Babel 解析器保留的"源码原文"（含引号与转义形式），改写它只影响代码生成阶段的输出形式；
• node.value保持不变，因此转译前后代码的运行时行为完全一致，"before\u2028after"与"before after"求值结果完全相同。

这种"文本层转换"策略保证了插件对 AST 的侵入性最小，即使后续还有其他插件继续处理该节点，也不会因字符串值的变动而产生意外。

边界场景：测试用例全解读

仓库在 test/fixtures/json-strings 下组织了 4 组 fixture，覆盖 U+2028 与 U+2029 ×（字符串字面量与指令字面量）的组合，每组均包含input.js（转译前）、output.js（期望转译结果）与exec.js（运行时断言）。测试通过 test/index.js 调用@babel/helper-plugin-test-runner执行，fixture 目录的 options.json 统一声明"plugins": ["transform-json-strings"]。

以 string-line-separator 的 exec.js 为例，它精确刻画了"反斜杠奇偶"的每种情况：

expect("\u2028".length).toBe(1); // 已是转义序列：不动 expect("before after".length).toBe(12); // 裸 U+2028：转义为 \u2028，运行值不变 expect(" ".length).toBe(1); // 单独裸 U+2028：转义 expect("\ ".length).toBe(0); // 1 个反斜杠（奇数）：已转义，原样保留 expect("\\ ".length).toBe(2); // 2 个反斜杠（偶数）：\u2028 前补一个反斜杠 expect("\\\ ".length).toBe(1); // 3 个反斜杠（奇数）：已转义，原样保留 expect("\\\\ ".length).toBe(3); // 4 个反斜杠（偶数）：\u2028 前补三个反斜杠

• 奇数反斜杠（1、3 个）时输出保持\等原始形式，运行值为空字符串或单反斜杠；
• 偶数反斜杠（2、4 个）时输出变为\\\u2028、\\\\\u2028，运行值保持为\+ U+2028、\\+ U+2028。

string-paragraph-separator 对 U+2029 验证了完全相同的矩阵，而 directive-line-separator 与 directive-paragraph-separator 则证明：指令字面量（如"use strict"场景下的裸分隔符）同样会被正确处理。

本地运行测试

在仓库根目录安装依赖后，可单独运行该插件的测试：

yarn jest packages/babel-plugin-transform-json-strings

与 @babel/preset-env 的协作

该插件属于 preset-env 内置的转换能力之一。在 preset-env 的 available-plugins.ts 中注册为transform-json-strings，并在其 package.json 中声明为工作区依赖。实际测试基线表明（见 preset-env 的 bugfixes 测试输出 中transform-json-strings { chrome < 66 }一行）：当目标浏览器为 Chrome 66 以下等不支持 JSON superset 语法的旧环境时，preset-env 会自动启用该插件进行降级转译；目标环境全部支持时则自动跳过，避免多余输出。这意味着日常项目通常无需手动安装此插件，配置好@babel/preset-env与browserslist目标即可获得按需转译。

小结

@babel/plugin-transform-json-strings是一个"小而精"的官方插件：它用一条正则加一个奇偶判断，就稳妥地解决了 U+2028/U+2029 在旧引擎上的兼容问题；通过只改写extra.raw原始文本、不改变 AST 语义值的设计，保证转译前后运行时行为零差异。无论是手动配置（"plugins": ["@babel/plugin-transform-json-strings"]），还是借助@babel/preset-env按目标环境自动启用，它都是处理 ECMAScript 2019 "JSON superset" 语法降级时的标准答案。理解它的实现细节，也能帮助你举一反三地掌握 Babel 插件中"文本层转换"这一通用模式。

【免费下载链接】babel🐠 Babel is a compiler for writing next generation JavaScript.项目地址: https://gitcode.com/gh_mirrors/ba/babel