Symbol.metadata 不存在于当前 JavaScript 标准中，ECMAScript 规范未定义该符号，浏览器和 Node.js 均不支持；应使用自定义 Symbol（如 Symbol('role')）配合 Reflect.metadata 等 API 实现安全、唯一、可分析的元数据挂载。
Symbol.metadata 是一个尚未被 ECMAScript 正式采纳的提案（截至 2026 年 4 月仍处于 Stage 2 阶段），它**不等于**已广泛支持的 Symbol.for('metadata') 或 Reflect.metadata 装饰器 API。目前没有浏览器或 Node.js 原生实现 Symbol.metadata 属性用于类属性元数据挂载——该符号本身在规范中尚未定义，也未出现在 TC39 提案仓库 的活跃列表中。
为什么不能直接用 Symbol.metadata？
当前 JavaScript 标准中：
-
Symbol.metadata并不存在于全局Symbol构造器上（调用会报TypeError: Symbol.metadata is not a constructor或undefined）； - ECMAScript 规范中未定义该 symbol，也没有配套的运行时行为（如自动收集、反射读取或装饰器绑定）；
- 混淆常来自 TypeScript 的
@Reflect.metadata装饰器或第三方库（如reflect-metadata）对Symbol('metadata')的私有使用，但这与标准化的Symbol.metadata无关。
实际可行的替代方案：用 Reflect.metadata + Symbol 保证唯一性
要为类属性挂载**可分析、不冲突、不暴露于普通枚举**的元数据，推荐组合使用：
-
Reflect.defineMetadata(key, value, target, propertyKey?)存储； - 自定义
Symbol作为 key（而非幻想中的Symbol.metadata），确保 key 全局唯一且不可被遍历； - 配合 TypeScript 的
emitDecoratorMetadata: true和reflect-metadatapolyfill。
示例：
// 定义专属元数据键（安全、唯一、不可枚举）const PROP_ROLE = Symbol('role'); // 不是 Symbol.metadata，但效果等价// 类定义
class User {<br> @Reflect.metadata(PROP_ROLE, 'primary-key')<br> id: number;<br><br> @Reflect.metadata(PROP_ROLE, 'sensitive')<br> password: string;<br>}// 运行时分析（需先 import 'reflect-metadata'
const role = Reflect.getMetadata(PROP_ROLE, User.prototype, 'password');<br>console.log(role); // 'sensitive'<br>console.log(Object.keys(User.prototype)); // [] —— 不暴露元数据
如何确保元数据可被工具链分析？
仅靠 Reflect API 不足以支撑构建时分析（如代码生成、校验器、IDE 提示）。需额外约定：
- 统一使用
Symbol键（避免字符串 key 冲突）； - 在 tsconfig.json 中启用：
"experimentalDecorators": true"emitDecoratorMetadata": true； - 入口文件顶部导入：
import 'reflect-metadata';； - 若需静态提取（如构建插件），可解析 TypeScript AST，查找
@Reflect.metadata(...)调用并提取 symbol 字面量或字符串 key。
注意：不要依赖非标准 Symbol 名称
诸如 Symbol.metadata、Symbol.classMetadata 等命名，目前既无规范依据，也无引擎支持。强行使用会导致：
- 运行时报错或静默失败；
- TypeScript 类型检查无法识别；
- 工具链（Babel、SWC、ESLint）无法识别语义，失去分析能力。
坚持用 Symbol('xxx') 自定义 + Reflect.*Metadata API，才是当前最稳定、可落地、可分析的元数据挂载方式。
