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:
console.log('初始化配置')
export const settings = { theme: 'light' }
同目录创建 main.mjs,运行 node 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 替换为:
export const createSettings = () => ({ theme: 'light' })
再将 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:
{
"name": "demo-tools",
"type": "module",
"exports": {
".": "./greet.mjs"
}
}
name 是包名,. 代表包的主入口,./greet.mjs 是入口实际指向的文件。type 表示该包的 .js 文件按 ESM 解释,前文已经介绍;.mjs 本身也明确使用 ESM。
创建公开的功能文件:
export const greet = name => `你好,${name}`
再创建调用文件,运行 node 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,而不是猜测内部路径。
"./greet": "./greet.mjs",使用者就能写 demo-tools/greet。左边是公开名称,右边是实际文件。❓ 知识问答
Q1:相对导入跟终端目录有关吗?
模块中的 ./ 跟当前模块文件有关,不是跟终端当前目录有关。
Q2:修改文件后缓存会自动刷新吗?
普通运行不会自动重新执行已加载模块,开发时通常重启程序。
Q3:包里有文件却不能导入是为什么?
可能被 exports 限制,也可能路径或模块格式不正确,应先看报错类型。
🧪 小练习
运行缓存示例,再给 settings 添加字段,观察两个导入变量是否看到相同变化。
// 请在这里编写代码
🎉 现在可以用自己的例子验证这些用法啦!
