私有字段

是什么，为什么存在

私有字段（private field） 是名称以 # 开头的类元素，例如 #balance。同一套语法也能声明私有方法、getter、setter 和静态成员。它们给类提供语言层面的 封装（encapsulation） 边界，不必再把 _balance 这样的命名约定当成访问控制。

私有名称只能写在声明它的类体内。account.#balance 若出现在类外，整个脚本会在解析阶段产生 SyntaxError，因此外层 try...catch 也接不到这个错误。account['#balance'] 虽然语法合法，却访问的是名为 "#balance" 的普通公开属性，与真正的私有字段无关。

你会在需要维护不变量的类中遇到私有元素，例如余额只能经过金额校验后修改，缓存内部索引不能由调用方替换。私有边界还能让实现者在不改变公开 API 的情况下调整内部表示。不过，它不是加密、权限检查或秘密存储机制；类自己的代码仍能公开其值，调试器和进程内攻击面也不受它约束。

私有字段适合由一个类完整拥有的状态。如果框架必须枚举字段、通用序列化器必须复制它们，或者子类需要直接扩展该状态，普通属性配合明确的公开契约往往更合适。应先决定谁能读取和修改状态，再选择语法。

工作原理

解析类定义时，引擎会建立一组词法私有名称。每个 #name 必须能在当前类体中解析到声明；同名字符串或 Symbol 都不能替代它。这个静态关系让拼错的私有名称在代码运行前就失败。

创建实例时，类会把自己的私有元素安装到对象上。随后执行 object.#name 时，引擎先做 私有标记（private brand） 检查：接收者必须经过该类的初始化。检查依据不是 instanceof、构造函数名称或原型形状，所以伪造相同公开属性不会通过。

声明与初始化

私有字段必须在类体中声明，可以在声明处初始化，也可以先取得 undefined，再由构造函数赋值。字段初始化器按源码顺序执行。较早的初始化器能读到已经初始化的字段，却不能提前读取尚未安装的后续私有字段。

实例字段属于各个实例，静态字段属于定义它们的类构造函数。私有方法与访问器使用同样的词法访问限制。delete this.#name 是语法错误；需要表示「没有值」时，应把字段设为 undefined、null 或业务定义的哨兵值。

标记与接收者

私有访问检查的是表达式左侧的实际对象。类方法可以读取另一个同类实例的私有字段，因为访问代码仍位于声明类体内，而且另一个实例带有相同标记。把该方法脱离实例调用，则会让 this 变成 undefined 或其他对象，并在访问私有字段时抛出 TypeError。

在声明类体内，#name in value 可以检查对象是否带有相应标记。它不会搜索原型链，也不会等同于 '#name' in value。右侧若是 null 或其他非对象值，该运算仍会抛出 TypeError，所以面向未知输入的检查应先排除这些值。

私有元素不是属性

普通属性由字符串键或 Symbol 键标识，并有可写、可枚举、可配置等属性描述符。私有元素不属于这套属性模型，所以 Object.keys()、Reflect.ownKeys()、Object.getOwnPropertyDescriptors() 和 for...in 都看不到它们。对象展开、Object.assign() 与 JSON.stringify() 也不会自动复制或输出它们。

这种不可见性避免了意外暴露，却不会自动保护字段引用的可变对象。如果公开 getter 直接返回私有数组，调用方仍能修改同一个数组。真正的封装取决于公开 API 是否返回只读视图、必要的副本或经过筛选的数据，而不只取决于 #。

示例

下面四个示例依次展示基础封装、标记检查、代理接收者和静态私有继承。所有输出都由本地 Node 24.14.0 执行对应文件得到。

用公开 API 维护余额

Wallet 只允许整数分币值进入状态，并通过 toJSON() 明确选择可公开的数据。反射只能看到普通属性，因此这个实例没有可枚举的自有键。

#cents 没有因为不可枚举而神秘地进入 JSON。输出余额来自显式的 toJSON() 方法；删除这个方法后，实例会序列化成 {}。因此，序列化内容是公开 API 的决定，而不是私有字段的自动行为。

校验方法也是私有元素。调用方只能通过构造函数和 deposit() 改变余额，这让「分币值必须是非负整数」这一不变量集中在类内。若其他公开方法也写入余额，它们仍须走同一套校验。

检查标记并区分同名字段

私有性按声明类区分，而不是按文本名称区分。GuestPass 可以再次声明 #code；它与 AccessPass 的 #code 是两个独立元素。

class AccessPass {
  #code;

  constructor(code) {
    this.#code = code;
  }

  static hasBrand(value) {
    return typeof value === 'object' && value !== null && #code in value;
  }

  readCodeOf(other) {
    return other.#code;
  }
}

class GuestPass extends AccessPass {
  #code = 'lobby';

  codes() {
    return [this.readCodeOf(this), this.#code].join(',');
  }
}

const first = new AccessPass('A-17');
const second = new AccessPass('B-42');
const guest = new GuestPass('G-07');

console.log(AccessPass.hasBrand(first));
console.log(AccessPass.hasBrand({ code: 'A-17' }));
console.log(first.readCodeOf(second));
console.log(guest.codes());

true
false
B-42
G-07,lobby

first 能读取 second，说明这里是类级私有，而不是「只有当前实例自己能读」。对象字面量即使保存相同字符串，也没有 AccessPass 的标记。通常不应把标记检查当成完整输入校验，它只说明对象经过了该类的初始化。

派生实例在 super() 期间取得基类私有元素，所以继承来的基类方法可以正常读取基类的 #code。但 GuestPass 的源码不能直接写基类的私有名称；它在自己的类体中写出的 #code 只会解析到派生类声明。

代理不会转移私有标记

Proxy 包装目标对象后，方法调用中的默认接收者是代理。代理能转发普通属性读取，但不会继承目标对象的私有标记。

class Meter {
  #value = 0;

  add(step) {
    this.#value += step;
    return this.#value;
  }

  read() {
    return this.#value;
  }

  static hasBrand(value) {
    return #value in value;
  }
}

const target = new Meter();
const directProxy = new Proxy(target, {});

try {
  directProxy.add(1);
} catch (error) {
  console.log(`direct proxy: ${error.name}`);
}

const boundProxy = new Proxy(target, {
  get(targetObject, property) {
    const value = Reflect.get(targetObject, property, targetObject);
    return typeof value === 'function' ? value.bind(targetObject) : value;
  },
});

console.log(boundProxy.add(2));
console.log(Meter.hasBrand(target), Meter.hasBrand(boundProxy));

direct proxy: TypeError
2
true false

绑定后的包装器让方法在 target 上运行，所以示例可以工作，但它并没有把标记复制到代理。这个通用 get trap 每次还可能创建新的绑定函数，并改变方法标识。生产代码通常应为需要代理的操作写明确的转发方法，而不是假设包装器完全透明。

同一种故障也会出现在脱离实例的方法中，例如把 meter.add 直接交给回调 API。应传入 (step) => meter.add(step)，或在注册时绑定一次接收者。测试时必须走真实回调路径，单独测试 meter.add(1) 看不到问题。

静态私有字段属于声明类

静态公开方法会被派生类继承，但基类的静态私有字段不会成为派生类自己的私有字段。使用多态的 this.#next 时，调用方选择的接收者会影响标记检查。

class IdSource {
  static #next = 100;

  static takeViaThis() {
    return this.#next++;
  }

  static takeFromBase() {
    return IdSource.#next++;
  }
}

class RegionalSource extends IdSource {
  static #next = 900;

  static takeRegional() {
    return this.#next++;
  }
}

console.log(IdSource.takeViaThis());
try {
  RegionalSource.takeViaThis();
} catch (error) {
  console.log(`derived receiver: ${error.name}`);
}
console.log(RegionalSource.takeFromBase());
console.log(RegionalSource.takeRegional());

100
derived receiver: TypeError
101
900

RegionalSource.takeViaThis() 中的 this 是派生类构造函数，它没有基类的静态私有标记。派生类恰好也声明了 #next 并不会改变结果，因为基类方法中的私有名称在词法上绑定到 IdSource 的声明。

如果计数器必须由整个继承层次共享，基类方法应明确使用 IdSource.#next，并接受它不再多态这一点。如果每个派生类都需要独立计数器，则应设计公开的注册表或让各类各自实现方法，不要试图让一个私有名称同时满足两种所有权。

陷阱

把语法错误放进 try...catch

修复方法： 通过类提供的公开方法测试行为。若确实要验证非法语法，应把源码字符串交给隔离的解析器或 Function 构造器，并断言它在编译阶段失败，不要把非法表达式直接写进当前文件。

返回私有可变对象

修复方法： 按 API 契约返回投影、迭代器或必要深度的副本。若元素对象本身也可变，只复制外层数组仍不够；应说明哪些层允许共享，并对修改路径编写测试。

假设子类能直接访问

修复方法： 基类若有意提供扩展点，应暴露范围明确的公开或受控方法。静态状态要明确属于基类还是各个派生类，再选择基类名称、公开注册表或派生类自己的实现。

丢失方法接收者

修复方法： 在 API 边界使用明确的包装箭头函数，或者只绑定一次方法。代理应逐项设计转发语义，并测试方法标识、getter、setter 与私有访问，而不是只检查一个普通属性读取。

把冻结和克隆当成私有状态操作

修复方法： 不可变性应由类的公开修改接口保证。持久化或跨线程传输时，定义显式的数据格式与重建函数，并测试往返结果；不要把通用对象工具的成功返回当成完整类实例复制。

延伸阅读

• ECMAScript 语言规范：字段定义
• MDN：私有元素
• V8：私有标记检查
• MDN：Proxy