PHP WeakMap 怎么避免对象缓存阻止垃圾回收

如果缓存只是保存“某个对象派生出来的数据”，又不应该让这个对象因此一直活着，就把对象本身作为 WeakMap 的键。WeakMap 对键使用弱引用：缓存项不会增加键对象的引用计数；当外部最后一个强引用消失时，对象可以被回收，对应缓存项也会从 WeakMap 中自动移除。

我第一次把对象实例直接塞进长期存活的缓存时，最容易忽略的并不是计算逻辑，而是“谁拥有谁”。缓存服务常驻，对象键也被容器持有，结果本来只服务一次请求的对象跟着缓存活了很久。WeakMap 的价值，就是把这种所有权关系改成“对象活着时可以查到附属数据，但缓存不负责让对象继续活着”。

一、变化不在缓存接口，而在对象所有权

PHP 8 提供的 WeakMap 是以对象为键的映射。它和普通数组、SplObjectStorage 最关键的差异，不是能否存值，而是键是否形成强引用。普通对象容器会持有对象；WeakMap 的键不增加对象引用计数。

因此，如果一个对象只剩 WeakMap 这一处“关联”，PHP 可以销毁该对象，并同时移除相应的键和值。PHP 官方文档也把它的主要用途描述为：缓存从对象派生、且不需要比对象活得更久的数据。

二、旧写法为什么容易让对象缓存越积越多

假设一个常驻服务为每个 Document 计算一次摘要。若使用 SplObjectStorage 保存对象键，缓存本身就是对象的拥有者。即使业务代码已经不再使用这些文档对象，只要缓存服务仍存在，键对象就不会因为业务引用消失而释放。

cache = new SplObjectStorage();
    }

    public function summary(Document $document): string
    {
        if (!$this->cache->contains($document)) {
            // 这里只缓存由对象内容派生出的字符串
            $this->cache[$document] = hash('sha256', $document->content);
        }

        return $this->cache[$document];
    }
}

这段代码不一定是错的。如果缓存的职责就是拥有这些对象，它很合理。问题出在“缓存只想关联数据，却无意中获得了对象所有权”。长生命周期 Worker、事件循环、队列消费者或测试进程里，这种差异会逐渐变得明显。

三、迁移到 WeakMap 的最小改动

迁移时保留原来的查询方式，把存储属性改成 WeakMap 即可。WeakMap 实现了 ArrayAccess 和 Countable，所以按对象取值、写值和计数都很直接。

 */
    private WeakMap $cache;

    public function __construct()
    {
        // WeakMap 只弱持有对象键，不承担对象生命周期
        $this->cache = new WeakMap();
    }

    public function summary(Document $document): string
    {
        if (!isset($this->cache[$document])) {
            // 缓存值最好只保存派生结果，不额外保存键对象
            $this->cache[$document] = hash('sha256', $document->content);
        }

        return $this->cache[$document];
    }

    public function size(): int
    {
        // count() 返回当前仍然存活的缓存项数量
        return count($this->cache);
    }
}

对我来说，这个改动最大的好处不是少写一次清理，而是让代码表达得更准确：SummaryCache 只认识对象，不拥有对象；对象消失后，它的派生摘要也没有继续保留的理由。

四、WeakMap 不能替你消除其他强引用

换成 WeakMap 后，如果缓存项仍不消失，先别急着怀疑垃圾回收。WeakMap 只保证“它自己的键引用是弱的”，并不影响其他地方的强引用。对象只要还保存在服务属性、数组、静态变量、闭包捕获变量或另一个对象属性中，就仍然是可达对象。

排查时我通常只问三个问题：

• 业务局部变量之外，还有没有属性或容器保存同一个对象？
• 缓存值是否又直接或间接保存了对象键？
• 当前需求真的是“对象消失就丢缓存”，还是其实需要 TTL、容量淘汰或跨请求复用？

WeakMap 解决的是对象键的所有权问题，不是通用缓存治理。它没有 TTL，也不能用字符串、整数作键；若数据需要跨请求、跨进程或按业务 ID 查询，仍应选择普通缓存或外部缓存系统。

五、用最小示例确认缓存项会自动移除

下面的验证同时观察 WeakMap 数量和 WeakReference。关键点是释放最后一个外部强引用，而不是手工删除 WeakMap 项。

content);
var_dump(count($cache)); // 预期为 1

// 释放业务代码持有的最后一个强引用
unset($document);

var_dump($weakReference->get()); // 预期为 null，对象已销毁
var_dump(count($cache));         // 预期为 0，缓存项同步移除

这个例子不需要调用 gc_collect_cycles() 才能说明 WeakMap 的基本语义。这里没有构造循环引用；对象的强引用计数归零后即可销毁。真实项目若存在复杂对象环，再把循环垃圾收集和弱键缓存分开分析，会比一上来强制 GC 更容易定位。

六、什么时候值得采用 WeakMap

我会在以下场景优先考虑 WeakMap：

• 为对象实例缓存反射结果、格式化结果、解析结果或临时元数据；
• 数据只在对象存活期间有意义；
• 缓存服务比单个业务对象活得更久；
• 清理逻辑不应散落在每个对象使用点。

而对象注册表、工作单元、需要显式拥有成员的集合，不应为了“自动清理”盲目换成 WeakMap。弱键意味着对象可能在没有其他强引用时消失；如果容器本来就负责维持对象生命周期，强引用反而是正确设计。

相关问题

WeakMap 从哪个 PHP 版本开始可用？

WeakMap 从 PHP 8.0 开始提供。若项目仍运行 PHP 7.4，可以使用 WeakReference 表达单个弱引用，但它不等同于原生的对象到值映射。

WeakMap 能使用字符串 ID 作为键吗？

不能。WeakMap 的键必须是对象。需要按字符串或整数 ID 查询时，应使用数组、PSR 缓存实现或外部缓存，并配置相应的过期与容量策略。

还需要手动 unset WeakMap 中的条目吗？

通常不需要为了对象销毁而手动删除；键对象销毁时条目会自动移除。但如果业务上要提前让缓存失效，仍可以使用 unset($map[$object]) 主动清理。

总结

WeakMap 并不是让 PHP “更积极地回收内存”，而是避免缓存容器仅因保存对象键就延长对象生命周期。把只依附于对象的派生数据放进 WeakMap，再确认其他地方没有强引用，就能让对象和缓存项在业务生命周期结束时一起消失。迁移前先判断容器是否应该拥有对象；这个判断比机械替换缓存类型更重要。