Node.js ESM 环境中的 HMR#

HMR（Hot Module Replacement / Hot Module Reload，模块热替换或热重载）是一种在应用运行时替换、更新模块代码而无需重启进程的技术。在前端开发中，像 Vite、Webpack 等打包器早已普遍支持 HMR，让开发者能即时预览修改效果。

在 Node.js 后端环境中，HMR 的可行性与所使用的模块系统密切相关：

• CommonJS (CJS)
  CJS 模块在加载时，require 会将模块实例缓存到 require.cache 这个 Map 中。开发者可以直接操作该缓存（例如删除条目），让下次 require 时重新加载模块，从而实现热替换。

• ECMAScript Module (ESM)
  ESM 的 import 是 JavaScript 语法关键字，由 V8 引擎内部处理。Node.js 在实现中将动态导入函数 import() 也封装为了 V8 层面的语法钩子，不暴露任何对应的模块缓存结构。
  这意味着在 ESM 环境下，开发者无法像在 CJS 那样通过操作 require.cache 来控制模块生命周期，直接造成了 HMR 场景下缓存不可见、无法失效的问题。

这就是 Node.js ESM 环境中的 HMR：模块缓存不透明，缺少官方 API 删除或替换模块实例，使得无打包器环境下的热重载实现难度大大增加。

CJS vs. ESM#

ESM 和 CJS 是两种不同的模块系统。其中 CJS 是 Node.js 在十多年前引入的，而 ESM 在近几年逐步成为了 JavaScript 开发的标准，它们之间的最大区别是导入和导出一个模块的方式:

1
// ESM
2
import fs from 'node:fs'
3
export function run() {}

1
// CJS
2
const fs = require('fs')
3
module.exports.run = function () {}

ESM的HMR#

HMR 即模块热替换(Hot Module Replacement)，在业务模块的开发过程中，任意保存一个源码文件，都可以在其他业务模块不停机的情况下，重载这个模块的代码。这对插件化框架开发极为有用。

目前，网络上常见的模块热替换基本为通过import缓存的是URL这一特性添加query等不影响URL地址内容的额外字符，让每次导入都使用不同的URL，防止导入被缓存的模块，实际上内部在每次加载还是会缓存URL，严重时可能导致内存泄露。

在某些框架如 Koishi 中，支持通过require.cache删除已经加载的模块来实现HMR，但require.cache仅仅在 CJS 环境下可用。在 ESM 环境下加载的模块根本不会写入这个对象(参考ESM-NoRequireCache)。你可以在许多 issue 中看到人们对此的抱怨和请求：

• ESM module reloading and module graph · Issue #51 · nodejs/tooling · GitHub 2
• hot reload modules w/ es6 modules · Issue #459 · nodejs/modules · GitHub 2
• Invalidate cache when using import · Issue #49442 · nodejs/node · GitHub 3

在2024年的 Koishi v5 预告中，Koishi 声称实在其元框架Cordis上实现了互联网上首个无需打包器的 ESM HMR 完整技术广泛应用的完整技术方案之一。

最终Koishi设计了两套完整的算法来解决上述问题。目前在 Cordis 仓库中使用的是其中一套。它基于一些 Node.js 内部 API，可以在守护进程中使用。后续如果有时间，Koishi也可能切换到另一套实现，它不依赖任何内部 API 就能安全地解决 CJS-ESM 多例和 ESM HMR 问题。

这里主要讲第一套方法(其实是作者也不知道第二种😰)。

—expose-internals#

这是一个神奇的参数，在Node.js官方文档中没有任何记载，只在其博客的更新日志与源代码README中少有提到。

1
# Internal Modules
2

3
The modules located in `lib/internal` directory are exclusively meant
4
for internal usage within the Node.js core. They are not intended to
5
be accessed via user modules `require()`. These modules may change at
6
any point in time. Relying on these internal modules outside the core
7
is not supported and can lead to unpredictable behavior.
8

9
In certain scenarios, accessing these internal modules for debugging or
10
experimental purposes might be necessary. Node.js provides the `--expose-internals`
11
flag to expose these modules to userland code. This flag only exists to
12
assist Node.js maintainers with debugging internals. It is not meant for
13
use outside the project.

该参数可以暴露Node.js JavaScript内部internals组中的模块，而我们的loadCache就在internal/modules/esm/loader中，由此我们可以通过添加该参数来操作loadCache，从而实现HMR。

loadCache 和 ModuleJob#

internal/modules/esm/loader 里导出的 loadCache 是一个 Map<url， ModuleJob>：

• url: 模块的标准化 URL（file://形式）
• ModuleJob: 负责执行模块加载生命周期（解析 - 链接 - 执行）

HMR 需要删除一个模块以及所有直接或间接依赖它的 ModuleJob，这样下次 import() 时 Node.js 会重新解析和执行代码，而不是直接复用已缓存的实例。

实现要点#

注意事项#