人人都会AI编程

模块缓存机制与缓存更新

更新时间：2026-07-10

在上一节我们详细拆解了 require 的加载全流程，其中提到过一个关键步骤：模块在首次加载完成后，会被放入缓存；后续对同一模块的 require 调用将直接从缓存中取出导出对象，而不会重新执行模块代码。 这一机制对 Node.js 应用的性能和行为都有重要影响，理解它的原理和操作方式，是进行模块化开发和排错的必修课。

1. 缓存储存在哪里

Node.js 的模块缓存是一个普通的 JavaScript 对象，挂在 require 函数上：

console.log(require.cache);

它的结构大致如下：

{
  '/absolute/path/to/module.js': Module {
    id: '/absolute/path/to/module.js',
    exports: { ... },
    parent: null,
    filename: '/absolute/path/to/module.js',
    loaded: true,
    children: [],
    paths: [ ... ]
  },
  ...
}

每个键是一个模块的绝对路径，值是该模块的 Module 实例。Node.js 在解析完模块的最终路径（通过路径解析、文件定位后得到绝对路径）后，会首先检查 require.cache 中是否已存在这个键。如果存在，直接返回该键对应的 module.exports；如果不存在，才执行完整的加载流程，并在加载成功后把新的 Module 实例存入 require.cache。

2. 缓存的意义：避免重复执行和性能优化

有了缓存之后，同一个模块无论被 require 多少次，其内部代码只会执行一次。这带来了两个直接好处：

  • 避免副作用重复执行：如果模块中包含初始化操作（比如建立数据库连接、启动定时任务、创建全局对象），重复执行可能导致多重连接或状态冲突。缓存保证了这些初始化仅发生一次。
  • 提高加载性能：对于大型项目，依赖树可能包含数百个模块。如果没有缓存，每条 require 语句都要重新解析路径、读取文件、编译执行，这会极大地拖慢启动速度，并增加 CPU 与 I/O 开销。

以一个计数器模块为例：

// counter.js
let count = 0;
module.exports = {
  increment() { count++; },
  getCount() { return count; }
};
// app.js
const c1 = require('./counter');
c1.increment();
const c2 = require('./counter');
console.log(c2.getCount()); // 输出 1，说明 c1 和 c2 指向同一个模块实例

counter.js 只被执行了一次，c1 和 c2 引用的是同一个 exports 对象，共享同一个 count 变量。这正是缓存机制在起作用——第二次 require('./counter') 并没有重新执行文件，而是直接返回了第一次加载并缓存的结果。

3. 缓存的唯一标识与细节

缓存键使用模块的绝对路径，而不是模块名称。因此，以下情况虽然看起来是“同一个模块”，但缓存仍会失效：

  • 路径写法不同但指向同一文件：如果项目中的 require('./foo') 和 require('./foo.js') 最终解析到同一个文件，require.resolve 通常返回相同的绝对路径，因此仍命中原缓存。但某些边界情况（如不同的 NODE_PATH）可能导致不同路径，导致重复缓存。
  • 不同版本的包：require('lodash') 和 require('lodash/core') 可能指向不同的文件，缓存自然不同。
  • 大小写问题：在区分大小写的文件系统（Linux）上，require('./Foo') 和 require('./foo') 会视为不同模块，缓存独立；但在 macOS/Windows 上默认大小写不敏感，可能导致意想不到的重复加载。

了解这一机制对排查模块单例失效、行为不一致等问题非常有帮助。

4. 缓存的查看与调试

我们可以在 Node.js 交互环境或代码中直接操作 require.cache 来查看和验证缓存：

// 在文件中打印缓存键列表
Object.keys(require.cache).forEach(key => {
  console.log(key);
});

或者用 Node.js 运行脚本时加上 --inspect-brk，在 Chrome DevTools 中打开，观察 Memory 面板中的 Object 内容。

5. 缓存更新：如何强制模块重新加载

有时我们希望强制重新执行某模块，以获取最新的代码或状态。直接修改 require.cache 可以实现这一点：

const path = require('path');

// 获取模块的绝对路径
const modulePath = require.resolve('./my-module');

// 删除对应缓存条目
delete require.cache[modulePath];

// 重新加载，此时会重新执行模块代码
const freshModule = require('./my-module');

注意： 仅删除顶层模块的缓存可能不够，因为该模块依赖的其他模块可能仍被缓存。如果希望完全重载一棵依赖子树，需要递归删除所有相关模块的缓存。社区封装了一些工具库（如 decache）来自动处理，但使用时仍需考虑对共享状态和循环引用的影响。

npm install decache
const decache = require('decache');
decache('./my-module');
const freshModule = require('./my-module');

6. 缓存更新的常见场景与风险

开发环境热重载：像 nodemon、pm2 --watch 等工具本质上是重启整个进程来加载新代码，从而完全绕过模块缓存。也有一些开发工具（如 Metro 在 React Native 中）采用更精细的模块替换方案（HMR），但这属于框架层面的高级封装，在普通 Node.js 应用中直接操作 require.cache 并不是主流。

单元测试隔离：测试框架（如 Jest）在每个测试文件执行时会创建独立的沙盒环境，模块缓存在不同测试套件之间自动重置，以保证测试的独立性。如果手动进行测试环境搭建，需要注意清理缓存以避免状态污染。

配置文件的动态加载：有时需要根据监控信号重新读取配置文件，但通常更推荐使用 fs.readFile 配合应用自身的配置管理器，而不是反复 delete require.cache 并重新 require，因为后者可能破坏其他模块对旧配置对象的引用，导致状态不一致。

生产环境： 绝大多数情况下，生产环境不应在运行时手动清除模块缓存，因为这会使模块的单例性丧失，可能导致内存泄漏、连接池重复创建、事件监听器叠加等严重问题。如果确实需要动态更新逻辑，应通过部署新版本或使用消息推送等方式重启进程，而不是在线“热更”。

7. 缓存与循环引用的相互作用

前面章节讨论过的循环引用，在缓存机制下会产生特定的行为：Node.js 在加载模块时，会先将一个未完成的 exports 对象存入缓存，然后再继续执行模块代码。因此，循环引用时被引用方可能获得一个不完整的导出对象。这也解释了为什么循环引用在 CommonJS 中是允许的，但容易出现不符合预期的结果。ESM 由于静态导入特性，会从根上拒绝类似的循环依赖，在加载阶段就会报错。

小结

模块缓存是 Node.js 模块系统的核心优化手段，它确保了模块的单例性和加载效率。理解缓存的存储位置、唯一标识、清除方法以及潜在风险，能够帮助我们更安全地编写代码和进行调试。在绝大多数情况下，信任并利用好缓存机制，避免手动干预，是更稳健的选择。下一节我们将深入探讨 CommonJS 的另一个关键细节——exports 与 module.exports 的区别与本质。