JavaScript WeakSet 和 WeakMap 的作用及使用场景

一、为什么需要弱引用集合：从强引用导致的内存泄漏谈起

在理解 WeakMap 和 WeakSet 之前，有必要先观察常规 Map 与 Set 的工作方式。常规集合在加入键或元素时，建立的是强引用（Strong Reference）。垃圾回收器（Garbage Collector, GC）在采用标记-清除算法判断内存对象是否存活时，会从根对象（全局 window、当前调用栈上下文等）出发遍历所有可达路径。

只要一个对象仍然处于常规 Map 的键或 Set 的元素中，该对象就具有通往根节点的可达路径。即使用户代码在外部已经执行了 element = null 或者从 DOM 树中删除了该节点，该对象所占用的内存也永远无法被释放，形成游离对象内存泄漏。

// 常规 Map 导致内存泄漏的典型例子
const registry = new Map();

function bindMeta() {
  let button = document.querySelector('#submit-btn');
  registry.set(button, { clickCount: 0, createdAt: Date.now() });
  // 业务处理完成，移除节点
  button.parentNode.removeChild(button);
  button = null;
}
// 此时 button 原本引用的 DOM 节点依然被 registry 强引用，内存无法释放！

面对这种痛点，传统做法必须是在组件卸载时手动调用 registry.delete(button)。但在复杂单页应用、大型组件库或第三方插件中，生命周期跨越多个模块，极容易遗漏注销逻辑。WeakMap 和 WeakSet 的诞生就是为了让对象和附加数据的生命周期自然重合。

二、WeakMap 的核心机制与三大经典使用场景

WeakMap 是一组键值对的集合，其关键特性是：键（Key）必须是对象（ES2023+ 扩展支持非注册 Symbol），且对键的引用是弱引用；而值（Value）可以是任意数据类型。一旦作为键的对象在外部没有任何强引用存在，该键值对就会被标记为垃圾回收的候选目标。

场景一：为 DOM 节点关联扩展数据或状态

在现代前端框架或无侵入式工具库中，我们常常需要针对特定的 DOM 节点记录元数据（例如点击频次、动画状态、权限标记或防抖定时器）。如果直接挂载到 DOM 元素自身（如 element._customData = ...），会污染原生对象，甚至可能与第三方脚本或浏览器内部属性发生命名冲突。

使用 WeakMap 可以构建一个与 DOM 完全解耦的映射表。当该 DOM 元素由于路由切换、列表重渲染被移除时，关联状态会自动随元素一同销毁，开发者完全不需要监听卸载事件去手动清理。

// 为 DOM 节点安全绑定状态示例
const elementStateMap = new WeakMap();

function trackButtonClick(buttonElement) {
  if (!elementStateMap.has(buttonElement)) {
    elementStateMap.set(buttonElement, { clicks: 0, lastClicked: 0 });
  }
  
  const state = elementStateMap.get(buttonElement);
  state.clicks += 1;
  state.lastClicked = Date.now();
  console.log(`按钮已点击 ${state.clicks} 次`);
}

// 当 buttonElement 从页面移除且变量置空时：
// 垃圾回收器会自动清理 buttonElement 以及存储在 elementStateMap 中的状态对象

场景二：实现对象的真正私有属性（类私有状态封装）

在 ES 标准官方引入类私有字段（#privateField）之前，JavaScript 开发者通常使用下划线命名约定（如 this._secret）或闭包来模拟私有属性。下划线只是一种口头约定，外部依然可以随意读取和篡改；而普通闭包则会导致所有实例共享或者在构造函数中重复创建方法实例。

利用模块级作用域内的 WeakMap，可以将类的私有状态存储在模块私有的映射表中。外部只能通过类暴露的原型方法访问，且当类实例被垃圾回收时，其对应的私有数据也会立即释放。

// 基于 WeakMap 封装类私有属性
const privateProps = new WeakMap();

class UserSession {
  constructor(username, token) {
    // 将实例作为 Key，私有字段封装在独立对象作为 Value
    privateProps.set(this, {
      token: token,
      loginTime: Date.now()
    });
    this.username = username; // 公开属性
  }

  getToken() {
    return privateProps.get(this).token;
  }

  isAuthenticated() {
    const data = privateProps.get(this);
    return Boolean(data && data.token);
  }
}

let session = new UserSession('alex', 'secret-token-8848');
console.log(session.username);        // 'alex'
console.log(session.token);           // undefined (外部无法直接访问)
console.log(session.getToken());      // 'secret-token-8848'
session = null; // 实例销毁，privateProps 内部关联条目在 GC 后自动释放

场景三：基于输入对象的计算结果缓存（Memoization）

当执行涉及复杂对象转换、AST 解析、大对象深度校验或数据加工时，缓存中间计算结果是提升性能的常见手段。如果使用普通的缓存容器，随着不断有新的对象传入，缓存表会越来越膨胀。

采用 WeakMap 作为缓存容器，只要输入对象在应用程序生命周期内仍然处于活跃状态，缓存就能命中并提供快速计算结果；一旦调用方弃用了该输入对象，旧缓存项自动随之废弃，实现了“自然淘汰”的零维护缓存。

// 基于 WeakMap 的对象计算结果自动缓存
const calculationCache = new WeakMap();

function parseComplexSchema(schemaObject) {
  if (calculationCache.has(schemaObject)) {
    return calculationCache.get(schemaObject);
  }

  // 模拟耗时的对象解析过程
  const compiledResult = Object.freeze({
    fields: Object.keys(schemaObject).map(k => k.toUpperCase()),
    compiledAt: Date.now()
  });

  calculationCache.set(schemaObject, compiledResult);
  return compiledResult;
}

三、WeakSet 的核心机制与典型使用场景

WeakSet 与 Set 类似，都是存放不重复值的集合。不同之处在于：WeakSet 的成员只能是对象（或符合规范的非注册 Symbol），且弱引用成员对象。在 WeakSet 中无法存储基础类型（如数字、字符串、布尔值）。

WeakSet 适合用来充当“对象标记集合”（Tagging Objects）。通过将某个对象添加进 WeakSet，我们可以在不修改对象本身结构的前提下，快速判断该对象是否具备某种状态。

场景一：递归遍历与序列化中的循环引用检测（Cycle Detection）

在实现深拷贝（Deep Clone）、对象比对、JSON 序列化或图形数据结构遍历时，最容易出现的严重故障是对象之间互相引用导致的调用栈溢出（Maximum call stack size exceeded）。

此时使用 WeakSet 记录所有已经访问过的节点，在遍历过程中通过 visited.has(current) 进行判定。由于 WeakSet 不持有强引用，即使被遍历的图结构非常庞大，也不会在算法执行后造成额外的内存驻留。

// 使用 WeakSet 防止对象深拷贝过程中的循环引用
function deepCloneWithCycleProtection(target, visited = new WeakSet()) {
  if (target === null || typeof target !== 'object') {
    return target;
  }

  // 检测当前对象是否正在处理链条中
  if (visited.has(target)) {
    throw new Error('检测到循环引用结构，深拷贝终止');
  }
  visited.add(target);

  const copy = Array.isArray(target) ? [] : {};
  for (const key of Object.keys(target)) {
    copy[key] = deepCloneWithCycleProtection(target[key], visited);
  }
  return copy;
}

// 验证循环引用检测
const nodeA = { name: 'Node-A' };
const nodeB = { partner: nodeA };
nodeA.partner = nodeB; // 构造 A <-> B 相互引用

try {
  deepCloneWithCycleProtection(nodeA);
} catch (err) {
  console.warn(err.message); // '检测到循环引用结构，深拷贝终止'
}

场景二：类实例安全校验（Brand Check / 品牌检查）

JavaScript 是一门基于原型的动态语言，函数的 this 上下文可以通过 call()、apply() 或 Reflect.apply() 随意变更。在某些对安全性敏感的 SDK 或核心模块中，我们希望确保某个方法只能被特定构造函数生成的真实实例调用，拒绝外部伪造的普通对象。

借助 WeakSet，可以在构造函数执行时将新生成的 this 加入私有集合中。在保护方法中，通过 brandSet.has(this) 进行断言验证。

// 基于 WeakSet 实现高安全度实例鉴权 (Brand Check)
const validInstances = new WeakSet();

class SecurityTokenManager {
  constructor(secret) {
    this.secret = secret;
    validInstances.add(this); // 盖上品牌印戳
  }

  executePrivilegedAction() {
    if (!validInstances.has(this)) {
      throw new TypeError('非法调用：必须在 SecurityTokenManager 真实实例上下文上执行');
    }
    return `特权操作已执行，签名校验通过`;
  }
}

const realManager = new SecurityTokenManager('k92-vault');
console.log(realManager.executePrivilegedAction()); // 正常执行

// 恶意或非法伪造上下文调用
const fakeObject = { secret: 'hacked' };
try {
  realManager.executePrivilegedAction.call(fakeObject);
} catch (e) {
  console.error(e.message); // '非法调用：必须在 SecurityTokenManager 真实实例上下文上执行'
}

四、核心限制与工程避坑指南

弱引用带来了自动垃圾回收的巨大红利，但由于底层垃圾回收器的工作时机是非确定性的（Non-deterministic），这直接导致 WeakMap 和 WeakSet 拥有与常规集合截然不同的限制条件。在实际编码中必须遵循以下工程约束：

关于垃圾回收时机不确定性的实战提醒

很多刚接触弱引用的开发者常常试图通过编写测试用例来验证 WeakMap.has(obj) 何时返回 false。然而，在标准的 JavaScript 规范中，垃圾回收何时触发完全由宿主运行时（V8、SpiderMonkey、JavaScriptCore）根据系统内存压力自行决定。

即使外界已经将引用置为 null，在垃圾回收器下一次运行之前，该对象仍然可能物理存在于堆内存中。因此，业务逻辑绝不能依赖“对象何时被真正回收”作为时序触发条件。如果需要监听对象被回收的事件通知，应当配合 ES2021 的 FinalizationRegistry 使用，但即便如此，回调通知也不保证绝对实时到达。

五、技术选型建议与总结

在实际项目架构设计中，选择 Map 还是 WeakMap，选择 Set 还是 WeakSet，可以通过以下三个连续提问快速定夺：

1. 你的键或元素是否包含非对象（如字符串 ID、数字 Code）？如果包含，必须选用常规 Map / Set。
2. 你需要不需要遍历列表、批量输出内容，或者需要获取数量（.size）？如果需要任何形式的枚举或计数，必须选用常规 Map / Set。
3. 数据的生命周期是否应该牢牢绑定在目标对象上（目标对象死，附加数据死）？如果是，且不需要遍历，应当坚决使用 WeakMap / WeakSet。

简而言之，WeakMap 与 WeakSet 并不是用于替代常规集合的“增强版”，而是专注于“对象生命周期跟随与安全标记”的专属精密工具。善用它们，可以在保持代码解耦与封装性的同时，将复杂的内存释放工作交给 JavaScript 底层引擎，从源头上杜绝内存泄漏隐患。