在JavaScript的七种原始类型当中，Symbol是比较特殊的一个。它并不是用来替代字符串或者数字的，而是为了解决一个长期存在的工程问题：如何在不依赖中心化命名管理的情况下，生成绝不会重复的值。当你调用Symbol()时，引擎会在内存中创建一个全新的、不可变的数据实体，哪怕你连续创建两个内容描述完全一样的Symbol，它们也不会相等。这种特性让Symbol成为对象属性键的理想选择，尤其是在多人协作或第三方库混入的场景中。
Symbol的基础语法与创建方式
创建一个Symbol非常简单，只需要调用全局函数Symbol即可，它可以接收一个可选的字符串参数作为描述符。这个描述符并不会影响Symbol的唯一性，仅仅用于在控制台调试时方便你区分不同的Symbol实例。例如let id = Symbol('user-id')和let id2 = Symbol('user-id')虽然描述相同，但id === id2的结果是false。这种设计从语言层面杜绝了键名意外碰撞的可能。
除了普通的Symbol()调用，规范还提供了Symbol.for()方法。与每次都新建不同，Symbol.for()会先去一个全局注册表中按描述符查找，如果已经存在就返回已有的Symbol，不存在才创建并登记。这相当于在全局范围内建立了一个可跨脚本共享的Symbol池。下面的代码展示了两者的差异，以及如何使用Symbol.keyFor()反向获取登记过的描述符。
// 普通创建，每次都唯一
const s1 = Symbol('tag');
const s2 = Symbol('tag');
console.log(s1 === s2); // false
// 全局注册表创建，按描述符复用
const g1 = Symbol.for('shared');
const g2 = Symbol.for('shared');
console.log(g1 === g2); // true
// 获取全局Symbol的描述符
console.log(Symbol.keyFor(g1)); // 'shared'
console.log(Symbol.keyFor(s1)); // undefined，因为未登记
在实际项目中，如果你希望某个Symbol能被多个独立加载的脚本共同识别，比如插件系统和宿主环境之间的约定标记，就应该使用Symbol.for。而如果只是模块内部为了避免属性被覆盖，普通Symbol()就足够了。需要特别注意的是，Symbol值不能参与数学运算，也不能和字符串做隐式拼接，否则会直接抛出异常，这点和字符串键的宽松处理完全不同。
Symbol作为对象属性的典型用法
Symbol最常见的用途是当作对象的属性键。由于Symbol键不会被常规遍历方法读取，它天然适合存放“半私有”的数据。比如一个用户类，你不想让外部随便通过user.name以外的方式篡改内部标识，就可以把标识挂在Symbol键上。下面的例子演示了如何用Symbol保护对象内部状态，同时仍然允许通过特定方法访问。
const PASSWORD = Symbol('password');
class Account {
constructor(name, pwd) {
this.name = name;
this[PASSWORD] = pwd;
}
check(input) {
return this[PASSWORD] === input;
}
}
const a = new Account('alice', '123456');
console.log(a.name); // 'alice'
console.log(a[PASSWORD]); // 外部可直接读，但无法猜出键名
console.log(Object.keys(a)); // ['name']，Symbol键不在其中
虽然上面例子里的Symbol键从语言机制上并非真正私有（通过Object.getOwnPropertySymbols仍能拿到），但它已经足以阻挡绝大多数无意的属性冲突和框架序列化时的意外泄露。很多流行库如Redux中间件、MobX响应式标记都依赖这种机制来挂载元数据。另外，Symbol键也不会被JSON.stringify处理，这意味着你可以安全地把业务对象传给接口而不必担心内部Symbol字段被发出去。
如果你确实需要列出对象上的Symbol属性，可以使用Object.getOwnPropertySymbols(obj)或者Reflect.ownKeys(obj)。前者只返回Symbol键，后者返回字符串键和Symbol键的总和。以下代码对比了几种遍历方式对Symbol键的覆盖程度，帮助你在调试时快速确认属性分布。
const sym = Symbol('x');
const obj = { a: 1, [sym]: 2 };
console.log(Object.keys(obj)); // ['a']
console.log(Object.getOwnPropertyNames(obj)); // ['a']
console.log(Object.getOwnPropertySymbols(obj)); // [Symbol(x)]
console.log(Reflect.ownKeys(obj)); // ['a', Symbol(x)]
内置Symbol与元编程能力
JavaScript在规范层面预定义了一批名为“众所周知Symbol”的内置符号，它们都挂在全局Symbol对象上，用来定制语言底层行为。最典型的就是Symbol.iterator，任何实现了该Symbol键且值为函数的对象，都可以被for...of循环遍历。这让开发者能够把自定义数据结构变成可迭代对象，而不需要依赖数组。
const myRange = {
from: 1,
to: 3,
[Symbol.iterator]() {
let current = this.from;
const self = this;
return {
next() {
if (current <= self.to) {
return { value: current++, done: false };
}
return { value: undefined, done: true };
}
};
}
};
for (const n of myRange) {
console.log(n); // 依次输出 1 2 3
}
除了迭代器，还有Symbol.toStringTag用于定制Object.prototype.toString.call的返回值，Symbol.hasInstance用于改写instanceof的行为，Symbol.toPrimitive用于控制对象被转为原始值时的逻辑。这些内置Symbol让框架作者可以深度介入语言运行时的默认流程，而不污染字符串命名空间。比如在写一个ORM模型时，你可以用Symbol.toPrimitive决定模型在模板字符串里到底显示主键还是描述信息。
使用内置Symbol时，不要尝试手动Symbol()去模拟，一定要直接用Symbol.iterator这类规范给定的引用。因为引擎只认得那一个固定身份，自己造的同名描述符不会被当作迭代协议。掌握这些Symbol不仅能让你写出更贴近语言本质的代码，也能在排查复杂库兼容性问题时迅速定位是不是某个元编程钩子被错误覆盖了。
SymbolJavaScript唯一值修改时间：2026-08-17 06:00:15