Node.js 模块加载机制:查找、缓存与 exports

根据导入路径排查找不到模块的问题,并理解模块为什么通常只初始化一次。

🎯 引言

学完这篇文章,你能根据导入路径排查找不到模块的问题,并理解模块为什么通常只初始化一次。


🧱 先判断导入的是什么

模块加载就是根据导入名称找到文件或内置功能,并执行其初始化代码。报“找不到模块”时,先区分三种来源:

  • node:path 以 node: 开头,指定 Node.js 内置模块,不需要安装。
  • ./greet.mjs 以相对路径开头,寻找当前模块旁边的文件。
  • dayjs 这样的包名,通常从当前模块位置逐级向父目录查找 node_modules。

例如 src/main.mjs 导入 ./greet.mjs,目标是 src/greet.mjs,不是终端当前目录里的 greet.mjs。这一点可以帮助你解释“从其他目录启动仍能正常导入”。

ESM 的本地导入应写完整扩展名,如 ./greet.mjs;目标是目录里的文件时,也明确写成 ./tools/greet.mjs。CJS 可以进行一些文件名补全,但不要把这些规则照搬到 ESM。


🛠 缓存:同一个模块通常只初始化一次

模块缓存会保存已经加载的模块结果,多个地方需要同一功能时可以复用。创建 settings.mjs:

settings.mjs
console.log('初始化配置')
export const settings = { theme: 'light' }

同目录创建 main.mjs,运行 node main.mjs:

main.mjs
import { settings as first } from './settings.mjs'
import { settings as second } from './settings.mjs'
console.log(first === second)

输出一次 初始化配置,然后输出 true。两个导入变量指向同一个对象,第二次导入没有重新创建配置。

如果需要观察共享状态,在 main.mjs 末尾追加:

first.theme = 'dark'
console.log(second.theme)

新增输出是 dark。这说明改变模块共享对象,会被其他导入者看到。如果每个调用者需要独立配置,将 settings.mjs 替换为:

settings.mjs
export const createSettings = () => ({ theme: 'light' })

再将 main.mjs 替换为:

main.mjs
import { createSettings } from './settings.mjs'
const first = createSettings()
const second = createSettings()
first.theme = 'dark'
console.log(second.theme)

运行后输出 light。模块仍会被缓存,但每次调用函数都会创建独立配置,避免一个调用者修改后影响另一个。

缓存依据是解析后认定的模块标识:CJS 通常按文件名,ESM 按模块地址。开发时修改文件后通常通过重启程序加载新代码,不应依赖重复导入自动刷新。


🧰 exports:包作者决定哪些入口可用

package.json 的 exports 声明包向使用者公开的入口。调用者依赖稳定入口,包作者才能调整内部文件,而不要求所有人跟着改路径。

下面用一个本地练习包观察这条规则,无需发布或安装第三方包。在新目录创建 package.json:

package.json
{
    "name": "demo-tools",
    "type": "module",
    "exports": {
        ".": "./greet.mjs"
    }
}

name 是包名,. 代表包的主入口,./greet.mjs 是入口实际指向的文件。type 表示该包的 .js 文件按 ESM 解释,前文已经介绍;.mjs 本身也明确使用 ESM。

创建公开的功能文件:

greet.mjs
export const greet = name => `你好,${name}`

再创建调用文件,运行 node use-package.mjs:

use-package.mjs
import { greet } from 'demo-tools'
console.log(greet('小明'))

结果是 你好,小明。Node.js 允许有名称和 exports 的包在内部按自己的包名引用自己,因此这里不需要安装 demo-tools。

如果把导入改成 'demo-tools/greet.mjs',会得到 ERR_PACKAGE_PATH_NOT_EXPORTED。文件虽然存在,但配置只公开了主入口,没有公开这个子路径。外部用户应按包说明使用 demo-tools,而不是猜测内部路径。

如果包确实需要额外公开一个入口,可以在 exports 中添加 "./greet": "./greet.mjs",使用者就能写 demo-tools/greet。左边是公开名称,右边是实际文件。

❓ 知识问答

Q1:相对导入跟终端目录有关吗?

模块中的 ./ 跟当前模块文件有关,不是跟终端当前目录有关。

Q2:修改文件后缓存会自动刷新吗?

普通运行不会自动重新执行已加载模块,开发时通常重启程序。

Q3:包里有文件却不能导入是为什么?

可能被 exports 限制,也可能路径或模块格式不正确,应先看报错类型。


🧪 小练习

运行缓存示例,再给 settings 添加字段,观察两个导入变量是否看到相同变化。

// 请在这里编写代码

🎉 现在可以用自己的例子验证这些用法啦!