How to Detect and Fix Node.js Memory Leaks in Production (Step-by-Step Guide)

如何在生产环境中检测并修复 Node.js 内存泄漏（分步指南）

Node.js is renowned for its high performance, event-driven architecture, and non-blocking I/O operations. Powered by Google Chrome’s V8 JavaScript engine, it enables developers to build scalable, real-time web applications. However, operating Node.js applications in production introduces a critical operational challenge: memory leaks. A memory leak occurs when an application retains references to objects that are no longer needed. Because the V8 Garbage Collector (GC) cannot identify these unused objects as freeable memory, the overall memory footprint grows over time. Eventually, this leads to performance degradation, high latency, and the infamous crash error: FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory. In this comprehensive guide, we will break down how Node.js manages memory, analyze the primary causes of leaks in production, explore step-by-step diagnostic techniques using built-in tools, and establish actionable solutions to prevent memory growth.

Node.js 以其高性能、事件驱动架构和非阻塞 I/O 操作而闻名。得益于 Google Chrome 的 V8 JavaScript 引擎，它使开发者能够构建可扩展的实时 Web 应用程序。然而，在生产环境中运行 Node.js 应用时，会面临一个严峻的运维挑战：内存泄漏。当应用程序保留了不再需要的对象的引用时，就会发生内存泄漏。由于 V8 垃圾回收器（GC）无法将这些未使用的对象识别为可释放内存，整体内存占用会随时间推移而增长。最终，这会导致性能下降、高延迟以及臭名昭著的崩溃错误：FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory。在本综合指南中，我们将剖析 Node.js 如何管理内存，分析生产环境中泄漏的主要原因，探索使用内置工具的分步诊断技术，并制定防止内存增长的可行方案。

Understanding V8 Memory Architecture in Node.js

理解 Node.js 中的 V8 内存架构

To fix memory leaks effectively, you must understand how Node.js organizes process memory. Memory allocated to a Node.js process is divided into two primary categories: Resident Set Size (RSS) and JavaScript Heap.

要有效地修复内存泄漏，必须了解 Node.js 如何组织进程内存。分配给 Node.js 进程的内存主要分为两类：常驻内存集（RSS）和 JavaScript 堆（Heap）。

1. Resident Set Size (RSS) 1. 常驻内存集 (RSS)

RSS represents the total portion of RAM allocated to the Node.js process in the host system. It consists of:

C++ Node.js Bindings: Internal engine structures.
Code Segment: The actual executing JavaScript code.
Stack: Local variables and primitive types.
Heap: Reference types, objects, arrays, and closures.

RSS 代表宿主系统中分配给 Node.js 进程的 RAM 总量。它包括：

C++ Node.js 绑定： 内部引擎结构。
代码段： 实际执行的 JavaScript 代码。
栈：局部变量和原始类型。
堆：引用类型、对象、数组和闭包。

2. The V8 Heap Structure 2. V8 堆结构

The Heap is managed directly by the V8 garbage collector and is further divided into two generations:

New Space (Young Generation): Where new allocations occur. Objects here are short-lived and frequently garbage-collected using a fast Scavenge algorithm.
Old Space (Old Generation): Objects that survive multiple garbage collection cycles in the New Space are promoted to the Old Space. This space is collected less frequently using the Mark-Sweep-Compact algorithm.

堆由 V8 垃圾回收器直接管理，并进一步分为两代：

新生代 (New Space)： 新分配对象的地方。这里的对象生命周期较短，并使用快速的 Scavenge 算法频繁进行垃圾回收。
老生代 (Old Space)： 在新生代中经历多次垃圾回收后仍然存活的对象会被提升到老生代。该区域使用标记-清除-整理（Mark-Sweep-Compact）算法，回收频率较低。

When a memory leak occurs, it almost always manifests within the Old Space Heap.

当发生内存泄漏时，几乎总是体现在老生代堆中。

The 4 Most Common Causes of Node.js Memory Leaks

Node.js 内存泄漏的 4 个最常见原因

1. Unintentional Global Variables 1. 无意的全局变量

Global variables in Node.js stay alive for the entire lifecycle of the process. If you inadvertently attach data to the global object or assign values without specifying const, let, or var, that data will never be collected.

Node.js 中的全局变量在进程的整个生命周期内都保持存活。如果你不经意间将数据附加到全局对象上，或者在赋值时没有指定 const、let 或 var，这些数据将永远不会被回收。

// BAD PRACTICE: Global leaks
// 不良实践：全局泄漏
function processUserData(user) {
  // Missing declaration creates a global variable
  // 缺少声明导致创建了全局变量
  userCache = userCache || [];
  userCache.push(user);
}

Solution: Always enforce strict mode ('use strict';) at the top of your files or use linters like ESLint to catch undeclared variables before deployment.

解决方案： 始终在文件顶部强制使用严格模式（'use strict';），或使用 ESLint 等代码检查工具在部署前捕获未声明的变量。

2. Forgotten Event Listeners & EventEmitters 2. 被遗忘的事件监听器和 EventEmitter

In Node.js, EventEmitter instances are widely used. If you attach event listeners to long-lived objects (such as process or singletons) without removing them when the associated request or task ends, the references remain indefinitely.

在 Node.js 中，EventEmitter 实例被广泛使用。如果你将事件监听器附加到长生命周期的对象（如 process 或单例）上，而在相关请求或任务结束时没有移除它们，这些引用将无限期保留。

// BAD PRACTICE: Listener leak
// 不良实践：监听器泄漏
const EventEmitter = require('events');
const globalEmitter = new EventEmitter();

function handleUserRequest(req, res) {
  globalEmitter.on('update', () => {
    res.send('Updated data'); // 'res' object is retained in memory! ('res' 对象被保留在内存中！)
  });
}

// GOOD PRACTICE: Removing listeners
// 良好实践：移除监听器
function handleUserRequest(req, res) {
  const onUpdate = () => res.send('Updated data');
  globalEmitter.on('update', onUpdate);
  res.on('finish', () => {
    globalEmitter.off('update', onUpdate);
  });
}

3. Closures Retaining Outer Scope References 3. 闭包保留外部作用域引用

Closures are a powerful JavaScript feature, but they hold references to variables in their parent scope. If a long-lived closure references an outer variable containing large datasets, those datasets cannot be garbage-collected.

闭包是 JavaScript 的强大特性，但它们会持有父作用域中变量的引用。如果一个长生命周期的闭包引用了包含大数据集的外部变量，这些数据集将无法被垃圾回收。

// BAD PRACTICE: Closure retaining scope
// 不良实践：闭包保留作用域
let unreferencedScopeHolder = null;
function replaceThing() {
  const originalThing = unreferencedScopeHolder;
  const unused = function () {
    if (originalThing) console.log("Hi");
  };
  unreferencedScopeHolder = {
    longStr: new Array(1000000).join('*'),
    someMethod: function () {}
  };
}
setInterval(replaceThing, 1000); // Heap growth accelerates continuously! (堆增长持续加速！)

4. Unbounded In-Memory Caching 4. 无限制的内存缓存

Using plain JavaScript objects or arrays as an in-memory cache without an eviction strategy (such as Time-To-Live or maximum size limits) will steadily consume available memory.

使用普通的 JavaScript 对象或数组作为内存缓存，且没有驱逐策略（如生存时间 TTL 或最大容量限制），将稳步消耗可用内存。

Solution: Replace plain object caches with specialized caching libraries like lru-cache, or offload caching entirely to distributed systems like Redis or Memcached.

解决方案： 使用 lru-cache 等专业缓存库替换普通对象缓存，或者将缓存完全卸载到 Redis 或 Memcached 等分布式系统中。

Step-by-Step: Diagnosing Memory Leaks in Production

分步指南：诊断生产环境中的内存泄漏

Step 1: Programmatic Heap Tracking 第 1 步：程序化堆跟踪

You can monitor memory consumption directly in your code using process.memoryUsage().

你可以使用 process.memoryUsage() 直接在代码中监控内存消耗。

function logMemoryUsage() {
  const memory = process.memoryUsage();
  console.log({
    rss: `${(memory.rss / 1024 / 1024).toFixed(2)} MB`,
    heapTotal: `${(memory.heapTotal / 1024 / 1024).toFixed(2)} MB`,
    heapUsed: `${(memory.heapUsed / 1024 / 1024).toFixed(2)} MB`,
    external: `${(memory.external / 1024 / 1024).toFixed(2)} MB`,
  });
}

Step 2: Generating Heap Snapshots 第 2 步：生成堆快照

To inspect exact memory allocation, generate .heapsnapshot files using Node’s built-in Inspector:

为了检查精确的内存分配，使用 Node 内置的 Inspector 生成 .heapsnapshot 文件：

const v8 = require('v8');
const fs = require('fs');

function takeHeapSnapshot(fileName) {
  const snapshotStream = v8.getHeapSnapshot();
  const fileStream = fs.createWriteStream(fileName);
  snapshotStream.pipe(fileStream);
}

Step 3: Analyzing Snapshots in Chrome DevTools 第 3 步：在 Chrome DevTools 中分析快照

Open Chrome and navigate to chrome://inspect. Click “Open dedicated DevTools for Node”. Go to the Memory tab, select Load, and upload your saved .heapsnapshot files. Compare two snapshots taken at different times using the Comparison view to spot growing object constructors.

打开 Chrome 并导航至 chrome://inspect。点击“Open dedicated DevTools for Node”。转到 Memory 选项卡，选择 Load，并上传你保存的 .heapsnapshot 文件。使用 Comparison（比较）视图对比不同时间点拍摄的两个快照，以找出不断增长的对象构造函数。

Conclusion

总结

Detecting and fixing memory leaks in Node.js requires a structured approach: understanding the V8 heap, identifying common bad practices, and taking regular heap snapshots to locate leaking references.

检测和修复 Node.js 中的内存泄漏需要结构化的方法：理解 V8 堆、识别常见的不良实践，并定期获取堆快照以定位泄漏的引用。