Node.js 的 require 语句表面上只是给出一个模块标识符，真正决定它能否加载到目标文件的是一套严格的路径解析规则。理解这套规则，能帮开发者避免大多数 Cannot find module 错误，也能在目录结构和包名设计上做出更合理的判断。解析过程可以简单概括为：先判断是否为核心模块，再区分是否带路径前缀，最后进入 node_modules 查找流程。

一、核心模块与文件模块的分流

require 第一步会判断模块名是否属于 Node.js 内置的核心模块。像 fs、path、http、os 这些模块在 Node 启动时已经编译进可执行文件中，并不依赖文件系统上的实际文件。因此当你在代码里写 require('fs') 时，即使当前项目里存在 node_modules/fs 目录，Node.js 也仍然会返回内置的 fs 模块。这一优先级规则非常重要，尤其是当第三方包与核心模块重名时，第三方包实际上永远不会被加载。

如果模块名不是核心模块，Node.js 会继续检查它是否以 ./、../、/ 开头，或者在 Windows 下以盘符开头。这些形式会被当作文件路径来处理，解析的基准目录是当前模块所在的目录，而不是执行 node 命令时的工作目录。很多路径错误正是由于误以为相对路径基于 process.cwd() 造成的。下面这段代码展示了核心模块与相对文件模块的加载入口差异：

const fs = require('fs');        // 核心模块，直接返回内置实现
const utils = require('./utils'); // 文件模块，基于当前文件所在目录解析

如果模块名既不是核心模块，也不带路径前缀，比如 require('axios')，它就会被当成包名，进入 node_modules 查找流程。这个分流机制让内置模块、项目内文件和第三方依赖各自拥有清晰的边界。

二、文件路径解析与扩展名补全

当 require 接收到一个明确的文件路径时，Node.js 不会直接报错说文件不存在，而是按照固定顺序依次尝试补全扩展名。假设代码中写的是 require('./config')，解析器会先查找完全匹配的 config 文件，然后依次尝试 config.js、config.json、config.node。如果这些文件都不存在，它会继续把 config 当作目录来处理。这个顺序并不是随机的，js、json、node 三种扩展名对应着 Node 原生支持的三类模块格式。

require('./config');
// Node.js 实际尝试顺序：
// ./config
// ./config.js
// ./config.json
// ./config.node
// ./config 目录

目录解析又包含两个层级。首先，Node.js 会查找该目录下的 package.json，如果存在且包含 main 字段，就根据 main 指定的相对路径继续解析入口文件。例如一个 lib 目录下的 package.json 写着 "main": "dist/main.js"，那么 require('./lib') 最终会加载 lib/dist/main.js。

如果目录下没有 package.json，或者 package.json 中没有有效的 main 字段，Node.js 会退回到索引文件机制，依次尝试 index.js、index.json、index.node。这种兜底规则让许多传统项目即使不写 main 字段也能通过目录名直接加载模块。不过从可维护性角度来说，明确写 main 字段仍然是更推荐的做法，它能减少解析路径中的不确定性。

三、node_modules 目录的向上查找机制

对于不带路径前缀的包名，Node.js 会从当前文件所在目录开始，逐级向上查找每一层父目录中的 node_modules 文件夹。比如当前文件路径是 /home/user/project/src/utils/helper.js，那么 require 一个包名时，查找顺序大致是 /home/user/project/src/utils/node_modules、/home/user/project/src/node_modules、/home/user/project/node_modules、/home/user/node_modules、/home/node_modules、/node_modules，直到在某一层找到目标包或到达文件系统根目录。

function resolveAsPackage(name, startDir) {
  let dir = startDir;
  while (true) {
    const candidate = path.join(dir, 'node_modules', name);
    const found = resolveAsFileOrDirectory(candidate);
    if (found) return found;
    const parent = path.dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

这个向上查找机制很像 JavaScript 的作用域链，内层目录的依赖会优先被命中。因此，如果项目根目录和某个子项目目录都存在同名依赖，不同位置的 require 可能实际加载到不同版本。也正是这种机制，让 npm 可以只在项目根目录安装一次依赖，而所有子目录中的文件都能共享该依赖。

需要区分的是，模块解析和模块缓存是两件事。解析过程会查找真实文件路径，一旦加载成功，Node.js 会以解析后的完整路径作为键缓存模块实例。所以同一个包即使被多处 require，通常也只会初始化一次。但缓存不会改变路径解析规则，如果解析失败，缓存不会起到补救作用。调试时可以通过 module.paths 查看当前模块的 node_modules 搜索目录列表。

四、常见错误定位与调试手段

Cannot find module 是 Node.js 项目中最常见的报错之一，但它的原因并不总是路径写错。文件系统大小写敏感差异就是一个典型问题。在 Linux 和 macOS 默认文件系统下，Config.js 和 config.js 是两个完全不同的文件，如果代码中写的是 require('./config')，但磁盘上文件名为 Config.js，解析会失败；同样的代码在 Windows 上却可能正常执行，因为 Windows 文件系统默认不区分大小写。这种跨平台差异会让问题显得更加隐蔽。

另一个常见误区是 package.json 的 main 字段写法。main 的值应该使用相对于包目录的路径，而不是以斜杠开头的绝对路径。写成 "main": "./src/index.js" 或 "main": "src/index.js" 都可以被正确处理，但如果写成 "main": "/src/index.js"，Node.js 会把它当成绝对路径，这往往不是开发者想要的结果。类似地，如果 main 指向的文件不存在，Node.js 会根据目录解析规则尝试 index 系列文件，但不同版本对失败后的回退行为可能存在细微差异，因此最好让 main 指向一个确实存在的文件。

在排查模块解析问题时，require.resolve 是很有用的工具。它会返回模块被解析后的完整路径，但不会实际执行该模块。借助它可以快速确认一个包名或相对路径到底指向了哪里。以下示例展示了如何查看模块解析结果，以及如何输出当前模块的 node_modules 搜索路径：

console.log(require.resolve('./utils'));  // 查看文件模块完整路径
console.log(require.resolve('axios'));    // 查看第三方包入口路径
console.log(module.paths);                // 查看当前模块的 node_modules 搜索列表

总的来说，Node.js 模块路径解析规则由核心模块优先级、路径前缀判断、扩展名补全、目录入口识别以及 node_modules 层层向上查找这五部分组成。掌握这些规则后，再遇到模块加载失败时，就可以按照核心模块、文件路径、包名查找这三个阶段逐步定位，通常很快就能清楚 require 语句最终指向的位置。