在Node.js中，当我们需要在一个对象被垃圾回收之后执行某些清理工作，语言标准提供的FinalizationRegistry就是一个值得了解的机制。它允许我们为一个对象登记一个回调函数，当这个对象被回收时，回调函数有可能被调用。需要注意的是，这种调用并不是确定性的，也不能用来替代正常的资源释放逻辑。
FinalizationRegistry的基本工作原理
FinalizationRegistry是ECMAScript 2021引入的语言特性，在Node.js 14.6.0及以上版本中可以直接使用，不需要任何外部依赖。它的核心思想是：你创建一个注册表实例，并向其中注册一个目标对象，同时提供一个在该对象被回收后可能执行的清理回调。注册表内部持有对目标对象的弱引用，因此不会阻止垃圾回收器回收这个目标对象。
当垃圾回收器确认目标对象不可达并准备回收时，会将之前登记的清理回调放进一个内部队列。随后在JavaScript事件循环的某个时间点，运行环境会从队列中取出回调并执行。正因为它依赖弱引用和GC行为，所以回调是否执行、何时执行都具有不确定性。你不能假设对象失去引用后会立刻触发回调，也不能依赖它来释放文件句柄或数据库连接。
下面是一段最基础的示例代码，展示了如何创建注册表并登记对象：
const registry = new FinalizationRegistry((token) => {
console.log('对象被回收了，token是：', token);
});
let obj = { name: 'temp' };
registry.register(obj, 'obj-token');
// 删除强引用，使obj可被回收
obj = null;
// 注意：此时回调不一定立即执行，取决于GC时机
在这段代码中，register方法的第一个参数是目标对象，第二个参数是传递给回调的token值。token可以是任意JavaScript值，常用来标识被回收的对象类型或ID。由于Node.js的GC是分代且按需触发的，你可能需要在测试时手动调用global.gc()并加上--expose-gc参数才能观察到回调。
在Node.js中实际应用与代码示例
虽然FinalizationRegistry不适合做关键资源管理，但它在调试内存泄漏、统计对象生命周期等辅助场景中很有价值。比如你想知道某个缓存对象是否真的被释放，可以为其登记一个回调来打印日志。以下示例演示了在Node.js模块中如何使用它来追踪对象销毁：
const { FinalizationRegistry } = globalThis;
function createTracker(name) {
const reg = new FinalizationRegistry((n) => {
console.log(`[tracker] 资源释放: ${n}`);
});
const resource = { id: Math.random(), name };
reg.register(resource, name);
return resource;
}
let cache = createTracker('user-cache');
// 模拟使用
setTimeout(() => {
cache = null;
if (global.gc) global.gc();
}, 1000);
在上面的例子中，我们将创建的对象返回给调用方，并在内部用注册表追踪。当调用方将cache置为null并触发GC后，回调可能输出释放日志。这种方式比手动在析构逻辑里打印更安全，因为它不影响对象本身的引用计数。
另一个常见用法是配合WeakRef一起使用。WeakRef可以让你持有对象的弱引用而不阻止回收，而FinalizationRegistry则告诉你对象何时没了。两者组合能够实现一些高级的缓存结构，例如自动清理的缓存表。但要注意，这种缓存绝不能假设条目一定会被及时清理，仍需设置上限防止内存膨胀。
const cache = new Map();
const reg = new FinalizationRegistry((key) => {
if (cache.get(key) && cache.get(key).deref() === undefined) {
cache.delete(key);
}
});
function setCache(key, obj) {
const wr = new WeakRef(obj);
cache.set(key, wr);
reg.register(obj, key);
}
该代码利用WeakRef保存对象弱引用，并在对象回收后通过注册表删除Map中的残留键。由于Map的键是普通字符串，不会阻止对象回收，因此整体结构相对安全。但这依然只是优化手段，不能替代显式清除逻辑。
使用时的注意事项与常见误区
很多人在初次接触FinalizationRegistry时，会误以为它可以像其他语言中的析构函数那样可靠地释放资源。实际上，Node.js的垃圾回收完全由V8引擎调度，在内存充足时可能长时间不触发GC，导致回调迟迟不执行。如果把关闭数据库连接、释放文件描述符等操作只放在注册表回调里，极有可能造成资源耗尽。
另一个误区是认为注册表回调中可以直接操作被回收对象。这是错误的，因为回调执行时目标对象早已不存在，你只能拿到之前传入的token。如果token本身又引用了那个对象，那么对象就不会被回收，这就违背了使用弱引用的初衷。因此token应当是轻量级的原始值或独立标识。
在Node.js服务长期运行的场景下，还应避免注册表回调里产生新的强引用或复杂计算。回调运行在事件循环中，若里面抛出异常且未被捕获，可能会影响进程稳定性。建议将回调逻辑写得尽量简单，只做日志或标记。若确实需要释放资源，正确做法是在业务代码中显式调用关闭方法，而将FinalizationRegistry作为兜底预警，例如打印一句“检测到未释放资源”的告警。
const warnReg = new FinalizationRegistry((label) => {
console.warn(`未显式释放的资源: ${label}`);
});
function openResource(label) {
const res = { label };
warnReg.register(res, label);
return res;
}
总结来说，Node.js中的FinalizationRegistry是一个观察对象回收的辅助工具，而不是资源管理的主控手段。理解它的弱引用本质和非确定性回调特征，才能在调试和监控中发挥价值，同时不引入新的隐患。
Node.jsFinalizationRegistry垃圾回收修改时间：2026-08-13 14:15:31