Node 14 下ECMAScript模块的包定义与查找规则问询

Node.js 内部对包的定义与npm生态的包概念同源，但有明确的实现层判定边界，核心是：可通过裸说明符导入的、具备独立封装边界的代码组织单元。一个结构上被Node识别为包的目录，必须满足两个基础条件：

• 处于Node模块查找链路覆盖的node_modules目录层级中（项目源码各级目录下的本地node_modules、全局安装对应的全局node_modules路径都属于覆盖范围）
• 目录下存在可被Node读取解析的package.json配置文件

注：项目自身根目录下的package.json所属的项目目录，哪怕结构特征完全符合上述要求，也不会被Node判定为“可通过裸说明符导入的包”——因为它不在node_modules的查找路径内，自然不满足裸说明符的定位条件。

实际的包定位是惰性、按导入路径逐层向上查找的，没有预扫描、全量登记所有包的流程，具体逻辑是：

• 当Node遇到需要解析的裸说明符时（比如import 'some-package/shuffle'、require('some-package')），会从当前发起导入的文件所在目录开始，依次向上遍历每一级文件路径，对每一级路径下的node_modules文件夹做匹配检查
• 在当前层的node_modules目录中，Node只会匹配和裸说明符前缀（也就是包名段）完全一致的子目录：比如带scope的包@my-team/utils，就会先匹配node_modules下的@my-team目录，再匹配这个目录下的utils子文件夹
• 对匹配到的目标文件夹，Node会检查其下是否存在可解析的package.json文件：如果有，就将这个文件夹判定为当前导入对应的包，终止向上查找；如果没有，则继续向上一级node_modules路径查找
• 整个过程不会提前扫描node_modules下的所有文件夹，也不会校验package.json里的name字段和文件夹名是否一致——哪怕文件夹名和里面写的包名不匹配，只要路径命中、有合法的package.json，就会被识别为包。

举个实际的例子：你在项目的node_modules下手动建了一个叫my-lib的文件夹，里面放了个空的package.json（内容为{}），那你在项目任何位置写import 'my-lib'，Node都能把这个文件夹识别为合法包；但如果这个文件夹里没有package.json，Node就算路径匹配到了，也不会把它当包，会继续往上查找。

两者的基础包判定逻辑（也就是定位“这是不是一个包”的流程）是完全一致的——不管是require()加载CommonJS模块，还是import加载ESM模块，找包的路径查找、目录匹配、package.json校验的流程没有任何区别。

差异全部出现在“识别到包之后，怎么解析包内部的入口文件、怎么响应子路径导入”的环节，具体区别是：

• CommonJS 场景下：识别到包目录后，会优先读取package.json的main字段作为入口，没有的话默认解析目录下的index.js；导入包的内部子路径时，可以自动补全.js/.json/.node后缀，不受exports字段的路径拦截限制。
• ESM 场景下：识别到同一个包目录后，会优先按照package.json的exports字段做路径映射，没有配置exports字段时，导入包内的子路径必须手写完整的文件扩展名，Node不会自动补全后缀；同时ESM解析时会额外读取package.json的type字段，判断包内的.js文件是按CommonJS语法还是ESM语法做解析。

内容的提问来源于stack exchange，提问作者Alana Storm