Node.js 的模块是怎么加载和查找的？

详细解析#

require 的查找顺序#

require(X)，调用方所在目录为 D
1. X 是核心模块 → 直接返回（node:fs、fs）
2. X 以 ./ ../ / 开头 → 按路径查找
   a. 当作文件：X → X.js → X.json → X.node
   b. 当作目录：X/package.json 的 main → X/index.js → X/index.json → X/index.node
3. X 以 # 开头 → 按最近 package.json 的 imports 字段映射（子路径导入）
   X 是当前包自己的名字且声明了 exports → 按自己的 exports 解析（自引用）
4. 裸模块名（lodash、@scope/pkg/sub）
   → D/node_modules → D/../node_modules → ... → 根目录的 node_modules
   → 找到包后，有 exports 字段按 exports 解析，否则按上面 2 的规则
5. 都找不到 → 抛出 MODULE_NOT_FOUND

• 每次查找前先看缓存。缓存的键是解析后的绝对路径（默认会把符号链接解析成真实路径）。在不区分大小写的文件系统上，require('./foo') 和 require('./FOO') 指向同一个文件，却会被当成两个模块各执行一次
• require.resolve(X) 只解析路径不执行，require.resolve.paths(X) 能看到会依次查找哪些 node_modules 目录
• 逐级向上查找就是 monorepo 和幽灵依赖能"碰巧能用"的原因：上层目录的 node_modules 里有，就能找到

模块缓存和循环依赖#

模块代码只在第一次 require 时执行一次，结果保存在 require.cache 中。Node.js 在执行模块代码之前就把它放进缓存，所以出现循环依赖时不会死循环，而是拿到对方当前的 exports：

// a.js（入口）
exports.done = false
const b = require('./b')
console.log('a 中看到 b.done =', b.done) // true
exports.done = true

// b.js
const a = require('./a') // a 还停在 require('./b') 这一行，拿到的是未完成的 exports
console.log('b 中看到 a.done =', a.done) // false
exports.done = true

如果 a 后面写的是 module.exports = {...} 整体替换，b 手里拿着的仍是旧对象，永远看不到新导出。ESM 的循环依赖行为不同，见 ES Module 和 CommonJS 的区别。

package.json 的 main、exports、type#

{
  "name": "my-lib",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.cjs"
    },
    "./utils": "./dist/esm/utils.js",
    "./package.json": "./package.json"
  }
}

• 条件导出：import 匹配 import 和 import()，require 匹配 require()，node 匹配 Node.js 环境，default 兜底。Node.js 按对象里的书写顺序取第一个匹配的条件，所以 default 要放最后，TypeScript 用的 types 一般放最前
• 限制深层导入：声明了 exports 后，require('my-lib/src/internal.js') 会抛出 ERR_PACKAGE_PATH_NOT_EXPORTED，连 package.json 本身都要显式导出才能读取。给已有的包加上 exports 可能让依赖深层路径的使用者报错，属于破坏性变更

ESM 的解析规则#

• 相对路径和绝对路径必须写完整文件名：import './utils.js'，写成 './utils' 会报 ERR_MODULE_NOT_FOUND；也不会自动找目录下的 index.js
• 不支持 NODE_PATH 和 require.extensions，裸模块名同样从 node_modules 逐级向上查找，再按 exports 解析
• 在 ESM 里能 import CommonJS 模块；反过来，较新的 Node.js 中 require() 也能加载不含顶层 await 的 ES 模块，具体版本和限制见 ES Module 和 CommonJS 的区别，需要兼容旧版本时仍然用 import()

面试官可能追问#

易错点#

• 认为 require 先找当前目录的同名文件：裸模块名只会去 node_modules 找，不会找 ./lodash.js
• 在 ESM 中省略 .js 扩展名，或者写 import './dir' 期望加载 index.js
• exports 中把 default 写在 import / require 前面，导致后面的条件永远匹配不到
• 循环依赖中用 module.exports = ... 整体替换导出，对方拿到的还是旧的空对象