企业官网建设流程全解析

Babel 私有属性存在性检查转换：@babel/plugin-transform-private-property-in-object 原理与实战

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

本指南围绕 Babel 官方插件@babel/plugin-transform-private-property-in-object展开，系统讲解它如何将 ES 类中的私有元素存在性检查#priv in obj转换为兼容旧环境的目标代码。你将掌握该插件的安装配置、五种转换策略的差异、基于 WeakMap/WeakSet 的底层实现原理，以及各类边界场景（嵌套类、半构造实例、非对象操作数等）的应对方案。

一、插件是什么：解决#priv in obj的兼容问题

ECMAScript 私有字段（Private Fields）与私有方法（Private Methods）引入了一种独特的in运算符用法——私有品牌检查（Private Brand Check）：

class Foo { #foo = 1; test(other) { return #foo in other; // 检查 other 是否具有 Foo 的 #foo 私有品牌 } }

#foo in other返回true当且仅当other是Foo的实例且其#foo私有元素已初始化。这一语法在旧浏览器与旧版 Node.js 中无法运行，因此 Babel 提供了转换插件@babel/plugin-transform-private-property-in-object。

该插件的官方定位（见 README.md）非常简洁：This plugin transforms checks for a private property in an object。它在@babel/preset-env中随私有字段/私有方法特性一起按需启用，也可独立安装使用（具体启用策略以 babel-preset-env 目录 中的插件清单为准）。

二、安装与基本使用

2.1 安装

使用 npm：

npm install --save-dev @babel/plugin-transform-private-property-in-object

或使用 yarn：

yarn add @babel/plugin-transform-private-property-in-object --dev

从 package.json 可以看到，该插件是一个type: "module"的 ESM 包，版本为8.0.1，其运行时依赖集中在三个 workspace 内部包上：

• @babel/helper-plugin-utils：提供declare插件声明包装；
• @babel/helper-create-class-features-plugin：提供私有元素转换的基础设施；
• @babel/helper-annotate-as-pure：用于对注入的new WeakSet()表达式标注/*#__PURE__*/注释，便于压缩器做死代码消除。

2.2 配置

在babel.config.js或.babelrc中启用：

{ "plugins": ["@babel/plugin-transform-private-property-in-object"] }

注意：该插件不会转换私有字段与方法本身，它只处理#priv in obj这一"检查"语法。私有字段与方法需要配合@babel/plugin-transform-class-properties、@babel/plugin-transform-private-methods使用（在 test/fixtures/private/options.json 中可以看到标准测试组合：transform-private-property-in-object+transform-class-properties+transform-private-methods+transform-classes）。当你使用@babel/preset-env或上述私有元素插件时，#priv in obj检查会由类特性插件统一接管；本插件的 visitor 只有在私有元素不被编译时（例如目标环境原生支持私有字段）才真正生效。

三、转换原理：源码级剖析

插件的完整实现位于 src/index.ts。其核心逻辑可以拆解为四个部分。

3.1 启用类特性基础设施

插件在pre()钩子中调用enableFeature(this.file, FEATURES.privateIn, loose ?? false)，将privateIn特性注册到@babel/helper-create-class-features-plugin中，这样私有字段/方法转换插件在遍历ClassExpression/ClassDeclaration节点时也会一并处理内部的#priv in obj检查。

3.2 visitor 匹配规则

visitor 监听BinaryExpression节点，命中条件有二：

if (node.operator !== "in") return; if (!t.isPrivateName(node.left)) return;

即只处理运算符为in、且左操作数为PrivateName（形如#foo）的表达式。

随后通过path.findParent向上查找最近的、包含同名私有元素的类节点，作为outerClass。

3.3 三种转换策略

根据私有元素的类型，插件采取完全不同的降级方案：

（1）实例私有方法 → 类级 WeakSet

私有方法没有"初始化"概念，因此整个类共享一个 brand 检查集合：

const id = getWeakSetId(classWeakSets, outerClass, outerClass, ...); path.replaceWith( template.expression.ast`${id}.has(${buildCheckInRHS(node.right, file)})` );

getWeakSetId会为类生成唯一的brandCheck标识符（scope.generateUidIdentifier），并注入两段代码：

• 类声明之前：var _Foo_brand = /*#__PURE__*/new WeakSet();
• 构造函数初始化位置：_Foo_brand.add(this);

最终输出形态（参见 private/method/output.js）：

var _Foo_brand = /*#__PURE__*/new WeakSet(); function Foo() { babelHelpers.classPrivateMethodInitSpec(this, _Foo_brand); } // ... return _Foo_brand.has(babelHelpers.checkInRHS(other));

（2）静态私有方法 → 恒等比较

静态私有方法无需集合，直接退化为类构造器恒等比较（参见 private/static-method/output.js）：

return babelHelpers.checkInRHS(other) === Foo;

源码中对这一分支还做了两件事：若类有名字，则调用unshadow沿作用域链逐级rename，防止外层同名绑定遮蔽类名；若类是无名表达式，则生成一个 uid 作为类名。

（3）实例私有字段 → 字段级 WeakSet

私有字段与私有方法不同：字段可能尚未初始化（详见后文"半构造实例"），因此不能简单复用类级集合。插件为每一个私有字段单独创建一个 WeakSet，并把id.add(this)注入到该字段的值初始化表达式中（injectToFieldInit，无初始值时用void expr兜底）。检查表达式变为：

return _foo.has(babelHelpers.checkInRHS(other));

完整输出见 private/field/output.js。

3.4 checkInRHS 与 RHS 边界

所有策略中都调用了buildCheckInRHS(node.right, file)。这是因为in运算符要求右侧必须是对象，而WeakSet.has()/Object.prototype.hasOwnProperty.call()对null/undefined会直接抛错。buildCheckInRHS来自@babel/helper-create-class-features-plugin，它会生成对运行时 helpercheckInRHS的调用，后者在遇到非对象 RHS 时抛出与原生#priv in obj一致的TypeError。测试目录中的 rhs-not-object/exec.js 专门验证了该行为。

四、五种转换模式与输出对比

仓库测试目录 test/fixtures 覆盖了五种配置模式，每种模式都包含accessor、field、method、static-accessor、static-field、static-method、nested-class等十余个场景用例。

4.1 严格模式（private）

严格模式使用WeakMap存字段值、WeakSet存 brand，并调用checkInRHShelper，语义与原生#priv in obj完全等价（见上文 3.3 节输出示例）。这也是 private/options.json 中默认的转换结果。

4.2 属性化假设模式（privateFieldsAsProperties）

当配置 assumptionprivateFieldsAsProperties: true时，私有字段被降级为普通可枚举属性（key 为唯一字符串），检查退化为hasOwnProperty。参考 assumption-privateFieldsAsProperties/options.json 与 assumption-privateFieldsAsProperties/field/output.js：

var _foo = /*#__PURE__*/babelHelpers.classPrivateFieldLooseKey("foo"); class Foo { constructor() { Object.defineProperty(this, _foo, { writable: true, value: 1 }); } test(other) { return Object.prototype.hasOwnProperty.call( babelHelpers.checkInRHS(other), _foo ); } }

4.3 符号化假设模式（privateFieldsAsSymbols）

privateFieldsAsSymbols: true与上一模式类似，但唯一键改为Symbol("foo")，见 assumption-privateFieldsAsSymbols/field/output.js：

var _foo = Symbol("foo");

两种 assumption 模式均牺牲了部分语义保真度（私有属性可被外部枚举/重写），换取更小的运行时开销，适用于对兼容性要求不高、追求输出体积的场景。

4.4 原生字段模式（to-native-fields）

当目标环境原生支持私有字段时（例如现代浏览器），私有元素本身不被编译，#priv in obj也会原样保留在输出中（参见 to-native-fields 目录 下各input.js与output.js的对比）。该模式下仍会编译非私有部分（如普通类方法），并验证了与transform-classes的协作行为。

五、边界场景与测试佐证

测试 fixtures 中专门覆盖了若干易错边界，直接体现了 src/index.ts 中的防御性处理：

嵌套类与重声明：nested-class、nested-class-redeclared、nested-class-other-redeclared三组用例验证了在嵌套类中，即使内部类重新声明了与外层同名的私有元素，插件也会正确绑定到最近的类。这是因为 visitor 用path.findParent就近查找包含匹配私有元素的类，且getWeakSetId以节点对象（而非名字字符串）为 key 区分不同的 WeakSet。

半构造实例（half-constructed）：私有字段允许在构造过程中对未初始化的字段做品牌检查（语义为false），因此插件坚持"每字段一个 WeakSet"并注入到字段初始化表达式，而不是依赖构造函数体执行。参见 to-native-fields/half-constructed-instance 与half-constructed-static用例。

非对象 RHS：rhs-not-object用例（带exec.js运行时断言）确保#priv in 123等写法在转换后依然抛出与原生一致的TypeError。

静态遮蔽（static-shadow）：静态方法检查要求checkInRHS(other) === ClassName，若外层存在同名变量会遮蔽类名，插件通过unshadow递归重命名来消除歧义；class-expression-in-default-param、class-expression-instance、class-expression-static则验证了类表达式场景（必要时包一层(() => Class){}(this)立即执行以创建独立作用域，见源码中outerClass.parentPath.scope.path.isPattern()分支）。

访问器（accessor）：accessor用例验证了带get/set的私有访问器（class accessor property）参与检查的转换；源码注释fixme: Support class accessor property提示访问器支持尚有演进空间。

六、loose 选项的废弃与 assumptions 迁移

在 Babel 8 中，插件的loose选项已被标记为废弃。源码 src/index.ts 中Options接口明确注释：

/** @deprecated Use the `privateFieldsAsProperties`(or `privateFieldsAsSymbols`), and `setPublicClassFields` assumptions instead. */ loose?: boolean;

一旦检测到loose被传入，插件会输出警告日志，提示改用 assumption 配置。正确迁移方式是在 Babel 配置顶层声明 assumptions：

{ "assumptions": { "privateFieldsAsProperties": true, "setPublicClassFields": true } }

assumptions 的好处是一次配置、全局生效：它不只作用于本插件，还统一影响transform-class-properties、transform-private-methods等所有相关插件的输出策略，避免了在多个插件里重复设置loose造成的不一致。

七、注意事项与最佳实践

1. 插件组合：该插件只负责#priv in obj检查；完整的私有元素降级需要与transform-class-properties、transform-private-methods（以及通常的transform-classes）配合，推荐直接使用@babel/preset-env按目标浏览器自动编排。
2. 语义保真度：严格模式（默认）输出与原生语义等价；privateFieldsAsProperties/privateFieldsAsSymbols会改变私有属性的可枚举性与可重写性，仅在明确接受这些差异时启用。
3. WeakMap/WeakSet 依赖：严格模式输出依赖WeakMap/WeakSet，对非常老的运行环境需搭配@babel/plugin-transform-regenerator之外的 polyfill（如core-js）补齐。
4. 静态成员检查：#staticPriv in obj的语义是"obj 是否就是该类本身"，输出为恒等比较，理解这一点有助于阅读编译产物。

通过本文的配置示例、五种模式对比与源码级原理拆解，你已可以独立完成#priv in obj语法的兼容方案选型与编译产物分析；如需深入阅读实现细节，可继续在仓库中查看 src/index.ts 及各模式下的 fixtures 目录。

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