FinalizationRegistry 的应用：在原生资源销毁时自动清理 JS 关联句柄

大家好，今天我们将深入探讨一个在现代JavaScript应用开发中至关重要的话题：如何利用FinalizationRegistry这个强大的Web API，在原生资源被销毁时，自动且优雅地清理与之关联的JavaScript句柄。这不仅能帮助我们构建更健壮、无内存泄露的应用，还能极大地提升开发体验和系统的稳定性。

问题背景：JavaScript垃圾回收与原生资源

在JavaScript的世界里，我们习惯于依赖垃圾回收（Garbage Collection, GC）机制来自动管理内存。当我们创建对象、数组、函数等JavaScript值时，它们占据内存；当它们不再被任何活动部分的代码引用时，GC会自动识别并回收这部分内存。这极大地简化了内存管理的复杂性，让我们能够专注于业务逻辑。

然而，JavaScript应用经常需要与各种“原生资源”进行交互。这些原生资源不直接由JavaScript引擎的GC管理，它们通常存在于JavaScript运行环境之外，例如：

• 文件句柄（File Handles）：在Node.js中打开一个文件，操作系统会分配一个文件句柄。
• 数据库连接（Database Connections）：连接到MySQL、PostgreSQL等数据库，会建立一个TCP连接并可能在服务器端占用资源。
• 网络套接字（Network Sockets）：进行网络通信时创建的套接字。
• WebGL/WebGPU纹理、缓冲区（Textures, Buffers）：在图形编程中，这些资源存在于显存中。
• WebAssembly内存（WASM Memory）：WASM模块直接操作的内存区域。
• C++或Rust绑定对象（Native Bindings）：通过FFI（Foreign Function Interface）或N-API等方式，JS对象可能包裹着指向原生内存或结构体的指针。

这些原生资源的一个共同特点是：它们必须被显式地释放或关闭。如果一个JavaScript对象包裹着一个原生资源，并且这个JS对象被GC回收了，但其对应的原生资源却没有被显式释放，那么就会导致原生资源泄露。虽然JavaScript的内存被回收了，但操作系统或硬件上的资源依然被占用，长此以往可能导致系统性能下降、服务崩溃，甚至耗尽可用资源。

考虑一个典型的场景：你有一个JavaScript类FileWrapper，它在构造函数中打开一个文件，并在析构时（或者通过一个close()方法）关闭这个文件。

class FileWrapper { constructor(filePath) { console.log(`[JS] Opening file: ${filePath}`); // 模拟调用原生API打开文件，获取一个原生文件句柄ID this.nativeHandle = NativeFileManager.openFile(filePath); this.filePath = filePath; } read() { if (this.nativeHandle === null) { console.error(`[JS] Error: File "${this.filePath}" is already closed.`); return; } console.log(`[JS] Reading from file: ${this.filePath} (handle: ${this.nativeHandle})`); // 模拟使用原生句柄进行读操作 // ... } close() { if (this.nativeHandle !== null) { console.log(`[JS] Explicitly closing file: ${this.filePath} (handle: ${this.nativeHandle})`); // 模拟调用原生API关闭文件 NativeFileManager.closeFile(this.nativeHandle); this.nativeHandle = null; // 标记为已关闭 } else { console.warn(`[JS] Warning: File "${this.filePath}" was already closed.`); } } } // 模拟原生文件管理器 const nativeResourceStore = new Map(); let nextHandleId = 1; class NativeFileManager { static openFile(path) { const handleId = nextHandleId++; console.log(`[Native] Allocating handle ${handleId} for ${path}`); nativeResourceStore.set(handleId, { path, status: 'open' }); return handleId; } static closeFile(handleId) { if (nativeResourceStore.has(handleId)) { const resource = nativeResourceStore.get(handleId); if (resource.status === 'open') { console.log(`[Native] Releasing handle ${handleId} for ${resource.path}`); nativeResourceStore.delete(handleId); } else { console.warn(`[Native] Handle ${handleId} was already closed.`); } } else { console.warn(`[Native] Attempted to close unknown handle ${handleId}.`); } } static getActiveHandles() { return Array.from(nativeResourceStore.keys()); } }

如果开发者总是记得调用fileWrapperInstance.close()，那么一切安好。但人非圣贤，孰能无过？一旦忘记调用close()，即使fileWrapperInstance被GC回收了，其对应的原生文件句柄this.nativeHandle仍将保持打开状态，直到程序退出或操作系统回收。这就是资源泄露。

为了解决这个问题，JavaScript引入了FinalizationRegistry。

FinalizationRegistry：连接JavaScript GC与原生资源清理的桥梁

FinalizationRegistry是一个JavaScript内置对象，它允许你注册一个清理回调函数，这个回调函数会在被注册的对象被垃圾回收器回收之后被异步调用。这提供了一种机制，使得我们可以在JavaScript对象生命周期结束时，自动触发对关联原生资源的清理操作。

其核心思想是：当JavaScript对象（例如我们的FileWrapper实例）不再被引用，并最终被GC回收时，FinalizationRegistry能够“感知”到这一事件，并执行预先注册的清理逻辑。

FinalizationRegistry的工作原理

1. 创建FinalizationRegistry实例：你需要创建一个FinalizationRegistry的实例，并为其提供一个cleanupCallback函数。这个回调函数将在注册的对象被GC回收后被调用。

   const myRegistry = new FinalizationRegistry(heldValue => { // heldValue 是你在注册时提供的数据，用于清理原生资源 console.log(`[FinalizationRegistry] Object was GC'd, cleaning up with heldValue:`, heldValue); // ...执行原生资源清理逻辑... });

2. 注册对象：使用myRegistry.register(target, heldValue, unregisterToken)方法来注册一个对象。

   • target：这是你想要监控其生命周期的JavaScript对象。当这个target对象被GC回收时，cleanupCallback将被触发。FinalizationRegistry会对target持有一个弱引用，这意味着target不会因为被注册而阻止其被GC回收。
   • heldValue：这是一个任意的JavaScript值，它会在target被GC回收时，作为参数传递给cleanupCallback。这个值通常包含清理原生资源所需的信息（例如，原生句柄ID、指针等）。FinalizationRegistry会对heldValue持有强引用，直到cleanupCallback被调用或注册被取消。注意：heldValue绝对不能直接或间接地强引用target对象，否则会导致循环引用，target将永远不会被GC回收。
   • unregisterToken(可选)：这是另一个任意的JavaScript值，它用于后续通过unregister()方法取消注册。如果提供，FinalizationRegistry会对unregisterToken持有弱引用。通常，target对象本身就可以作为unregisterToken，因为我们希望在target被明确关闭时取消自动清理。

3. 取消注册：如果原生资源在target对象被GC回收之前就已经被显式地清理了（例如，用户调用了fileWrapperInstance.close()），那么我们需要通过myRegistry.unregister(unregisterToken)方法来取消之前的注册。这可以防止cleanupCallback再次尝试清理一个已经关闭的资源，避免潜在的错误或性能开销。

关键特性与注意事项

• 异步与非确定性：FinalizationRegistry的回调是异步的，并且执行时机是非确定性的。它只会在GC运行之后才被调用，而GC何时运行，取决于JavaScript引擎的内部策略和系统负载。这意味这回调可能在target对象变得不可达后的几毫秒、几秒、甚至更长时间才执行。在某些极端情况下（例如程序在GC运行前就退出），回调甚至可能永远不会执行。
• 安全网而非主要机制：由于其非确定性，FinalizationRegistry应该被视为原生资源清理的最后一道安全网，而不是主要的清理机制。开发者仍然应该优先通过显式的close()或dispose()方法来管理原生资源。
• 主线程执行：cleanupCallback通常在主线程上执行。这意味着你不应该在其中执行长时间运行或阻塞性的操作，以免影响应用的响应性。
• heldValue的引用问题：如前所述，heldValue必须谨慎设计，确保它不会强引用target对象。通常，heldValue应该是一个原始值（如数字、字符串）或一个不包含target引用的简单对象。

实战应用：自动清理文件句柄

现在，让我们将FinalizationRegistry应用到之前的文件包装器示例中，来构建一个更健壮的ManagedFile类。

// 模拟原生文件管理器 (与之前相同) const nativeResourceStore = new Map(); let nextHandleId = 1; class NativeFileManager { static openFile(path) { const handleId = nextHandleId++; console.log(`[Native] Allocating handle ${handleId} for ${path}`); nativeResourceStore.set(handleId, { path, status: 'open' }); return handleId; } static closeFile(handleId) { if (nativeResourceStore.has(handleId)) { const resource = nativeResourceStore.get(handleId); if (resource.status === 'open') { console.log(`[Native] Releasing handle ${handleId} for ${resource.path}`); nativeResourceStore.delete(handleId); } else { console.warn(`[Native] Handle ${handleId} for ${resource.path} was already closed.`); } } else { console.warn(`[Native] Attempted to close unknown handle ${handleId}.`); } } static getActiveHandles() { return Array.from(nativeResourceStore.keys()); } } // ---------------------------------------------------------------------- // FinalizationRegistry 的初始化 // 创建一个 FinalizationRegistry 实例，用于监听 ManagedFile 对象的GC // 当 ManagedFile 对象被GC时，会调用这个回调，并传入注册时提供的 handleId const fileCleanupRegistry = new FinalizationRegistry(handleId => { console.log(`n[FinalizationRegistry Callback] ManagedFile object was GC'd. Attempting to clean up native handle: ${handleId}`); NativeFileManager.closeFile(handleId); }); // ---------------------------------------------------------------------- // ManagedFile 类，集成 FinalizationRegistry class ManagedFile { constructor(filePath) { this.filePath = filePath; // 1. 打开原生文件，获取句柄 this.nativeHandle = NativeFileManager.openFile(filePath); // 2. 将当前 ManagedFile 实例注册到 FinalizationRegistry // - target: this (ManagedFile 实例自身) // - heldValue: this.nativeHandle (当GC发生时，这个值会被传递给 cleanupCallback) // - unregisterToken: this (使用实例自身作为取消注册的token，方便在显式关闭时取消自动清理) fileCleanupRegistry.register(this, this.nativeHandle, this); console.log(`[JS] ManagedFile created for ${filePath}, native handle: ${this.nativeHandle}`); } read() { if (this.nativeHandle === null) { console.error(`[JS] Error: File "${this.filePath}" is already closed.`); return; } console.log(`[JS] Reading from file: ${this.filePath} (handle: ${this.nativeHandle})`); // 模拟使用原生句柄进行读操作 } close() { if (this.nativeHandle !== null) { console.log(`[JS] Explicitly closing ManagedFile for ${this.filePath}, native handle: ${this.nativeHandle}`); // 1. 显式关闭原生句柄 NativeFileManager.closeFile(this.nativeHandle); // 2. 关键步骤：取消在 FinalizationRegistry 中的注册 // 这可以防止在 ManagedFile 实例随后被GC时，FinalizationRegistry 再次尝试关闭这个已经关闭的句柄 fileCleanupRegistry.unregister(this); this.nativeHandle = null; // 标记为已关闭 } else { console.warn(`[JS] Warning: ManagedFile "${this.filePath}" was already closed.`); } } }

演示场景与行为观察

为了更好地理解FinalizationRegistry的行为，我们设计几个演示场景。由于JavaScript的GC是非确定性的，我们不能保证回调会立即执行。在Node.js环境中，可以使用--expose-gc标志并在代码中通过global.gc()强制触发GC，但这在浏览器环境中是不推荐或不可行的。通常，我们会模拟GC的发生，或者在长时间运行的程序中观察其效果。

场景一：显式关闭文件

在这种情况下，我们遵循最佳实践，显式地调用close()方法。

console.log("--- Scenario 1: Explicitly closing file ---"); let file1 = new ManagedFile("data.txt"); file1.read(); console.log(`Active native handles before close: ${NativeFileManager.getActiveHandles()}`); file1.close(); console.log(`Active native handles after close: ${NativeFileManager.getActiveHandles()}`); file1 = null; // 解除引用，使其可被GC // 强制GC (仅Node.js with --expose-gc) // global.gc(); console.log("-------------------------------------------n");

预期输出：

1. [Native] Allocating handle 1 for data.txt
2. [JS] ManagedFile created for data.txt, native handle: 1
3. [JS] Reading from file: data.txt (handle: 1)
4. Active native handles before close: 1
5. [JS] Explicitly closing ManagedFile for data.txt, native handle: 1
6. [Native] Releasing handle 1 for data.txt
7. Active native handles after close:(空数组)
8. 不会有[FinalizationRegistry Callback]的输出，因为我们显式地取消了注册。

场景二：忘记关闭文件（依赖GC自动清理）

这是FinalizationRegistry发挥作用的主要场景。我们创建文件，但不调用close()，然后解除对JS对象的引用，等待GC发生。

console.log("--- Scenario 2: Forgetting to close file, relying on GC ---"); let file2 = new ManagedFile("config.json"); file2.read(); console.log(`Active native handles before unreferencing: ${NativeFileManager.getActiveHandles()}`); file2 = null; // 解除引用，使其成为GC的候选对象 console.log(`Active native handles after unreferencing: ${NativeFileManager.getActiveHandles()}`); // 模拟等待GC发生 (在实际应用中，这可能是程序运行一段时间后自动发生) // 在Node.js中，可以通过 global.gc() 强制触发GC，但需要 --expose-gc 启动参数 console.log("nSimulating a delay for GC to potentially run..."); // 通常你会看到这里有一个延迟，GC会在某个时刻运行 // 如果没有 global.gc()，你可能需要运行更长时间或创建更多对象来触发GC // 或者，在浏览器中，这会是一个不可预测的等待 for (let i = 0; i < 100000000; i++) { /* busy-wait to encourage GC */ } // 粗略模拟 // global.gc && global.gc(); // 尝试强制GC console.log(`Active native handles after simulated GC delay: ${NativeFileManager.getActiveHandles()}`); console.log("----------------------------------------------------------n");

预期输出：

1. [Native] Allocating handle 2 for config.json
2. [JS] ManagedFile created for config.json, native handle: 2
3. [JS] Reading from file: config.json (handle: 2)
4. Active native handles before unreferencing: 2
5. Active native handles after unreferencing: 2(此时JS对象已不可达，但GC可能尚未运行)
6. Simulating a delay for GC to potentially run...
7. [FinalizationRegistry Callback] ManagedFile object was GC'd. Attempting to clean up native handle: 2(这一行会在GC发生后异步出现)
8. [Native] Releasing handle 2 for config.json
9. Active native handles after simulated GC delay:(空数组，如果GC成功执行)

场景三：混合行为与多个资源

console.log("--- Scenario 3: Mixed behavior with multiple resources ---"); let file3 = new ManagedFile("log.txt"); let file4 = new ManagedFile("settings.ini"); console.log(`Active native handles initially: ${NativeFileManager.getActiveHandles()}`); file4.close(); // 显式关闭一个 let file5 = new ManagedFile("temp.bin"); console.log(`Active native handles mid-run: ${NativeFileManager.getActiveHandles()}`); file3 = null; // 让 file3 成为GC候选 // file5 仍然被引用着，或者我们模拟它在某个作用域结束后被释放 console.log("nSimulating more work and potential GC opportunities..."); for (let i = 0; i < 200000000; i++) { /* more busy-wait */ } // global.gc && global.gc(); // 尝试强制GC console.log(`Active native handles at end of scenario 3: ${NativeFileManager.getActiveHandles()}`); file5.close(); // 最后显式关闭 file5 console.log(`Active native handles after all closes: ${NativeFileManager.getActiveHandles()}`); console.log("---------------------------------------------------------n");

预期输出：

1. file3(handle 3) 和file4(handle 4) 被创建。
2. file4.close()被调用，handle 4 被显式关闭并从fileCleanupRegistry中取消注册。
3. file5(handle 5) 被创建。
4. file3 = null，handle 3 变为GC候选。
5. 经过一段时间和/或GC触发后，FinalizationRegistry的回调会被调用，清理 handle 3。
6. file5.close()被调用，handle 5 被显式关闭并从fileCleanupRegistry中取消注册。
7. 最终所有原生句柄都应该被释放。

通过这些场景，我们可以清晰地看到FinalizationRegistry如何作为一道重要的安全网，确保即使开发者疏忽了显式清理，原生资源最终也能得到释放。

WeakRef与FinalizationRegistry的关系

在讨论FinalizationRegistry时，经常会提及WeakRef（弱引用）。它们都是ECMAScript 2021（ES12）引入的新特性，都与对象的弱引用和GC相关，但用途不同：

• WeakRef：允许你创建一个对对象的弱引用。这意味着如果只有WeakRef实例引用一个对象，该对象仍然可以被垃圾回收。你可以通过weakRef.deref()方法尝试获取原始对象的强引用。如果对象已被GC回收，deref()将返回undefined。WeakRef主要用于观察对象的生命周期，或者构建一些缓存机制（当内存不足时，缓存项可以被回收）。
• FinalizationRegistry：用于在对象被GC回收之后执行清理操作。它不提供访问已回收对象的能力，而是通过heldValue传递清理所需的上下文信息。

虽然它们都处理弱引用，但FinalizationRegistry是专门为资源清理而设计的，而WeakRef更侧重于生命周期观察和缓存管理。在某些高级场景中，它们可以结合使用，例如，使用WeakRef存储一个对象的特定属性，并在FinalizationRegistry的回调中根据这个属性来清理，但对于大多数原生资源清理场景，FinalizationRegistry搭配heldValue足以胜任。

进阶考量与最佳实践

1. 避免heldValue强引用target

这是使用FinalizationRegistry最重要也是最容易出错的地方。如果heldValue强引用了target对象，那么target将永远不会被GC，从而导致FinalizationRegistry的回调永远不会被调用，资源也永远不会被清理。

错误示例：

// 假设 MyResource 有一个 .id 属性 class MyResource { /* ... */ } const registry = new FinalizationRegistry(resource => { // 这里的 resource 实际上是 MyResource 实例 // 如果 MyResource 实例被GC了，这个回调才会触发 // 但如果 heldValue 强引用了 MyResource 实例，它就永远不会被GC console.log(`Cleaning up resource with ID: ${resource.id}`); }); let myObj = new MyResource(); // 错误！heldValue 强引用了 myObj registry.register(myObj, myObj, myObj); myObj = null; // 尝试解除引用，但因为 heldValue 的强引用，myObj 仍不会被GC

正确做法：heldValue应该只包含清理所需的信息，且这些信息不应直接或间接强引用target。原始类型（如数字、字符串）是安全的。

const registry = new FinalizationRegistry(resourceId => { console.log(`Cleaning up resource with ID: ${resourceId}`); }); let myObj = new MyResource(); // 正确！heldValue 只是资源ID，不会强引用 myObj registry.register(myObj, myObj.id, myObj); myObj = null; // 现在 myObj 可以被GC了

2.unregister的重要性

正如在演示中看到的，当原生资源被显式关闭时，务必调用unregister。这有几个好处：

• 避免重复清理：防止FinalizationRegistry在对象被GC时再次尝试清理一个已经关闭的资源。
• 资源效率：减少不必要的清理回调的调度和执行。
• 避免错误：某些原生API在尝试关闭一个已经关闭的句柄时可能会抛出错误或产生警告。

3. 性能考量

FinalizationRegistry的回调是在GC发生之后才执行的，这可能会引入轻微的性能开销，因为JavaScript引擎需要在GC周期中额外处理这些注册。因此，不应滥用FinalizationRegistry，仅在确实需要自动清理原生资源的场景中使用。回调函数内部也应尽量轻量，避免执行复杂的计算或长时间阻塞操作。

4. 作为后备方案

再次强调，FinalizationRegistry是一个安全网。它不能替代良好的资源管理实践，例如使用try...finally块、using声明（未来的JavaScript提案）或dispose()方法来显式管理资源。在同步代码流中，显式清理总是更及时、更可预测的。FinalizationRegistry的价值在于捕获那些因编程错误或意外情况而未能显式清理的资源。

总结

FinalizationRegistry是JavaScript语言为解决原生资源管理痛点而提供的一个强大工具。它通过在JavaScript对象被垃圾回收后触发清理回调，有效地弥补了JavaScript垃圾回收机制无法直接管理原生资源的不足。

然而，它的非确定性和异步特性决定了它不应作为主要的资源管理策略，而应作为一道坚实的安全网，与显式的close()或dispose()方法协同工作。正确理解并应用FinalizationRegistry，能够帮助我们构建更健壮、更可靠的JavaScript应用程序，有效防止原生资源泄露。