Symbol

是什么，为什么存在

Symbol 是一种基本值，每个值都有自己的标识。调用 Symbol('order.id') 两次会得到两个不相等的值；其中的字符串只是调试描述，不参与相等比较。typeof 对这类值返回 'symbol'。

对象的 属性键（property key） 只能是字符串或 Symbol。字符串键适合公开、可读和可序列化的字段；Symbol 键适合由某段代码持有并共享其值、但不应与普通名称冲突的扩展槽位。第三方库可以为同一个对象添加各自的 Symbol 属性，而不必争抢 _metadata 一类字符串名称。

Symbol 还有第二项职责：JavaScript 用一组 内置 Symbol（well-known symbol） 表示语言协议的入口。对象实现 [Symbol.iterator]() 后，for...of 与展开语法就知道怎样读取它；实现 [Symbol.toPrimitive]() 后，转换算法会调用这个钩子。这里的 Symbol 不负责隐藏数据，而是给协议提供不会与业务字段碰撞的标准键。

当数据需要写入 JSON、数据库字段、URL 或跨进程消息时，通常应使用稳定字符串，而不是 Symbol。需要真正封装类状态时，应使用 #privateField；拥有 Symbol 引用的代码仍可读写对应属性，Reflect.ownKeys() 也能发现它。

你会在库扩展点、对象元数据、迭代协议、类型转换和反射代码中遇到 Symbol。普通业务记录若没有名称冲突或协议定制需求，字符串键通常更直接。

工作原理

标识与描述

Symbol(description) 每次都创建新的未注册 Symbol。description 会先转换成字符串并保存为调试信息；省略参数时描述为 undefined，显式传入空字符串时描述是 ''。描述相同不建立任何共享关系。

Symbol 是函数，却不能与 new 一起使用。Symbol 基本值本身不可修改；对象上以它为键的属性仍可重新赋值、删除或配置，这些行为由属性描述符决定。

Symbol 值来自三个不同入口，不能只凭显示文本判断来源：

相等比较按标识判断。普通 Symbol 即使描述相同也不相等；从同一个全局注册表键取得的值相等；同一个内置 Symbol 属性每次读取也得到同一值。Symbol 没有像字符串那样按内容比较的分支。

作为属性键

计算属性语法 { [key]: value } 与方括号访问 object[key] 会保留 Symbol 键。点号语法要求源码中的固定标识符，不能表示 Symbol。只要生产者与消费者持有同一个 Symbol 值，它们就能访问同一个属性。

“是否为自有属性”“是否可枚举”和“键是字符串还是 Symbol”是三个独立维度。对象字面量和普通赋值创建的 Symbol 属性默认可枚举；Object.keys() 仍忽略它，因为该方法只选择可枚举的自有字符串键。

这张表解释了“看不见”的不同含义。Symbol 属性可能从 Object.keys() 和 JSON 中消失，却仍被对象展开复制；如果要保留所有自有键和描述符，应从 Reflect.ownKeys() 与 Object.getOwnPropertyDescriptors() 开始设计，而不是组合几个只处理字符串的方法。

全局注册表

Symbol.for(key) 先把 key 转成字符串，再查询 全局 Symbol 注册表（global symbol registry） 。已有条目就返回原 Symbol，否则创建并登记一个新值。Symbol.keyFor(symbol) 只对已注册 Symbol 返回对应字符串；未注册 Symbol 返回 undefined，非 Symbol 参数会抛出 TypeError。

这里的“全局”不是网络、数据库或持久化全局。注册表只提供运行时约定的标识复用，而且任何知道键字符串的代码都能取得同一个 Symbol。它既不是秘密存储，也不能替代跨边界的数据编码。

注册表键本身可能碰撞。库若确实需要注册键，应把命名空间作为公开契约，并由一个权威模块定义；只需要包内共享时，导出 const key = Symbol(...) 更容易控制所有权。

内置协议键

内置 Symbol 是规范算法识别的固定键。消费者通常不会直接调用所有钩子，而是执行普通语法或方法，例如展开对象、转换值或使用 instanceof；算法随后读取对应的 Symbol 属性。

实现一个钩子就承担该协议的返回值与状态契约。Symbol.iterator 方法返回普通数组而不是迭代器时，消费阶段会失败；Symbol.toPrimitive 返回对象时也会抛出 TypeError。Symbol 只解决钩子命名，不能让实现自动正确。

示例

下面四个示例依次验证标识、属性可见性、迭代协议和转换协议。所有输出都由本地 Node 24.14.0 执行对应文件得到。

区分局部标识与注册标识

第一个程序对比相同描述的普通 Symbol 与相同键的注册 Symbol。最后一段还展示安全的显式字符串转换与失败的隐式转换。

localOne 与 localTwo 的描述只帮助调试，不能让消费者重建键。sharedOne 与 sharedTwo 则由同一个注册表条目提供，所以标识相同。String(localOne) 有显式转换的特殊行为，模板字面量中的隐式转换会抛出 TypeError。

看清 Symbol 属性的选择规则

订单对象包含一个普通字符串键、一个可枚举 Symbol 键和一个不可枚举 Symbol 键。程序分别检查键集合、描述符、对象展开与 JSON 输出。

const internalId = Symbol('internalId');
const auditNote = Symbol('auditNote');
const order = {
  number: 'A-17',
  [internalId]: 42,
};

Object.defineProperty(order, auditNote, {
  value: 'checked',
  enumerable: false,
});

console.log(JSON.stringify(Object.keys(order)));
console.log(Object.getOwnPropertySymbols(order).map(String).join(','));
console.log(Reflect.ownKeys(order).map(String).join(','));
console.log(Object.getOwnPropertyDescriptor(order, internalId).enumerable);
console.log(Object.getOwnPropertyDescriptor(order, auditNote).enumerable);

const copy = { ...order };
console.log(Reflect.ownKeys(copy).map(String).join(','));
console.log(copy[internalId]);
console.log(JSON.stringify(order));

["number"]
Symbol(internalId),Symbol(auditNote)
number,Symbol(internalId),Symbol(auditNote)
true
false
number,Symbol(internalId)
42
{"number":"A-17"}

对象展开复制了可枚举的 internalId，但没有复制不可枚举的 auditNote。JSON 输出忽略两个 Symbol 键，与它们的 enumerable 值无关。任何依赖“展开会丢失 Symbol”或“可枚举 Symbol 会进入 JSON”的代码都会在这里暴露错误。

用内置 Symbol 实现可重复迭代

Batch 把 [Symbol.iterator]() 写成生成器方法，因此每次调用都创建新的迭代器状态。它还提供 Symbol.toStringTag，改变标准对象标签的显示结果。

class Batch {
  constructor(orderIds) {
    this.orderIds = [...orderIds];
  }

  *[Symbol.iterator]() {
    yield* this.orderIds;
  }

  get [Symbol.toStringTag]() {
    return 'Batch';
  }
}

const batch = new Batch(['A-17', 'B-04']);

console.log([...batch].join(','));
console.log([...batch].join(','));
console.log(Object.prototype.toString.call(batch));
console.log(Reflect.ownKeys(Batch.prototype).map(String).join(','));

A-17,B-04
A-17,B-04
[object Batch]
constructor,Symbol(Symbol.iterator),Symbol(Symbol.toStringTag)

两次展开都完整输出，证明遍历没有共享一个已耗尽的游标。两个协议方法位于原型上，并且以 Symbol 为键；Reflect.ownKeys() 能看到它们，Object.keys() 则不会列出这些不可枚举的类成员。

定义明确的基本值转换

发票对象根据转换提示返回文本或分值。第二个对象故意违反协议，用于确认钩子必须返回基本值。

const invoice = {
  cents: 1250,
  [Symbol.toPrimitive](hint) {
    if (hint === 'string') return 'EUR 12.50';
    return this.cents;
  },
};

console.log(String(invoice));
console.log(+invoice);
console.log(invoice + 250);
console.log(`${invoice}`);

const broken = {
  [Symbol.toPrimitive]() {
    return {};
  },
};

try {
  Number(broken);
} catch (error) {
  console.log(error.name);
}

EUR 12.50
1250
1500
EUR 12.50
TypeError

String() 与模板字面量请求字符串提示，一元加号请求数字提示，加法在这里使用默认提示。这个设计只适合语义明确的值对象；若不同调用方可能误解“发票加 250”的含义，命名方法 format() 与 totalCents() 更容易审查。

陷阱

用描述重新创建键

修复方法： 从一个模块导出并复用同一个 Symbol 常量。确实需要按字符串约定共享时才使用 Symbol.for()，并把注册表键当作公开命名空间管理。

把 Symbol 当作私有字段

修复方法： 需要防止类外直接访问时使用 #privateField 或闭包状态。Symbol 适合防碰撞扩展键；不要把调试界面里不显眼误写成安全边界。

混淆枚举、复制与序列化

修复方法： 为每个边界写出键选择矩阵，并用字符串键、Symbol 键、不可枚举键和继承键测试。需要协议数据跨边界时，把它显式投影为有名称的字符串字段。

让注册表承担过多职责

修复方法： 注册表键应来自受控常量，并带有稳定命名空间。包内共享优先导出普通 Symbol；真正的数据交换使用经过验证的字符串标签和显式编解码。

对 Symbol 做隐式字符串转换

修复方法： 允许 Symbol 键的诊断代码使用 String(key)，业务协议则分别处理字符串与 Symbol。不要依赖 description 作为唯一名称，因为它可以缺失或重复。

延伸阅读

• ECMAScript 语言规范：Symbol 类型
• ECMAScript 语言规范：内置 Symbol
• ECMAScript 语言规范：Symbol 对象
• ECMAScript 语言规范：Symbol.for()
• ECMAScript 语言规范：JSON.stringify()