WeakMap 生命周期怎么配置或排查

PHP 的 WeakMap 生命周期不能靠 php.ini 参数配置。它只接受对象作为键，而且键不会增加对象的引用计数：当对象只剩 WeakMap 中这一条弱引用时，垃圾回收会让对象和对应条目一起消失。排查时不要先改缓存参数，应先找还有哪些变量、属性、数组或闭包持有这个对象。

官方手册地址：https://www.php.net/manual/en/class.weakmap.php

先判断：你要配置的其实不是 WeakMap

我遇到过最容易误判的一类问题：代码把对象放入 WeakMap 后，开发者希望通过某个 TTL、GC 开关或缓存容量参数控制它什么时候消失。WeakMap 没有这类配置。它的核心约束是“键对象活着，条目才活着”；对象被业务代码最后一次强引用释放后，条目才有机会被移除。

因此，下面三种现象要分开看：

用最小复现确认对象什么时候离开

先把业务对象替换成一个带析构日志的类。下面的输出是示意，重点是比较 unset($item) 前后的 count()，而不是把图中的文字当作本机运行证据。

id}\n";
    }
}

$cache = new WeakMap();
$item = new Job('A-17');
$cache[$item] = ['normalized' => true]; // 值只保存派生数据，不回指对象。

echo "before: ", count($cache), "\n";
unset($item); // 释放最后一个已知强引用，条目随后应被移除。
gc_collect_cycles(); // 只用于帮助定位循环引用，不是 WeakMap 的配置开关。
echo "after: ", count($cache), "\n";

正常情况下，before 是 1，析构日志出现在释放附近，after 是 0。gc_collect_cycles() 不是“让 WeakMap 立即过期”的按钮；没有循环引用时，真正决定结果的是强引用是否已经归零。

count 不下降时，沿四条强引用路径排查

如果 unset($item) 后条目仍在，最常见的原因不是 WeakMap 失效，而是对象还藏在别处。可以把对象的持有关系按“容器、属性、闭包、值回指”四条路径逐项缩小：

1. 容器：数组、集合、全局变量或静态属性里仍有对象元素。
2. 属性：某个服务、队列任务或关联对象的属性仍指向它。
3. 闭包：回调通过 use ($item) 捕获了对象，队列或事件监听器尚未释放。
4. 值回指：WeakMap 的值保存了键对象本身，弱键虽不加引用，但值中的强引用会把对象留住。

 $node]; // 容器仍然持有同一个对象。
$map[$node] = ['label' => 'derived'];

unset($node);
echo count($map), "\n"; // 仍可能是 1，因为 $holder['node'] 还在。
unset($holder['node']); // 移除最后的业务强引用后再观察。
echo count($map), "\n";

排查时可以先给关键对象增加唯一标识，在创建、进入容器、注册回调、移除容器的位置打日志。不要只在 WeakMap 读取处加日志，那只能看到结果，无法说明哪条路径还持有对象。

把 WeakMap 当作对象附属缓存，而不是永久缓存

WeakMap 很适合保存“由对象推导出的临时数据”，例如规范化结果、计算标记或对象级元信息；它不适合承诺固定 TTL、跨请求持久化或按数量淘汰。需要稳定保留的结果，应使用明确生命周期的数组、PSR-16 缓存或数据库，并由业务代码负责失效。

生产排查可以保留一份小清单：键是否始终为对象；写入的值是否回指键；对象是否被容器或闭包捕获；循环结束后是否仍有循环变量；析构日志和 count() 是否在同一个请求阶段观察。若必须手动删除条目，可使用 unset($map[$object])，但这只是移除映射，不等于能替代对象引用管理。

相关问题

WeakMap 能不能用字符串作为键？

不能。键必须是对象；传入字符串、整数等标量会触发类型错误。若业务主键是字符串，应选择普通数组或其他明确键值的缓存结构。

为什么 unset 变量后 WeakMap 还有条目？

unset 只移除这个变量名。属性、数组元素、闭包捕获或 WeakMap 值里的回指仍可能是强引用，先沿这些路径继续排查。

WeakMap 和 SplObjectStorage 怎么选？

对象被回收时仍希望保留条目，用 SplObjectStorage 等强持有结构；只想让附属数据跟随对象自然消失，用 WeakMap，并接受条目没有固定保留时间。