模块解析和加载

返回上层文档

\Module resolution and loading

Node.js 有两种模块解析和加载方式,具体取决于模块的请求方式。

\Node.js has two types of module resolution and loading, chosen based on how the module is requested.

当通过 require() 请求模块时(CommonJS 模块默认可用,并且可以使用 createRequire() 在 CommonJS 和 ES 模块中动态生成):

\When a module is requested via require() (available by default in CommonJS modules, and can be dynamically generated using createRequire() in both CommonJS and ES Modules):

解析:

\Resolution:
- 由 require() 发起的解析支持文件夹作为模块。
  
  \The resolution initiated by require() supports folders as modules.
- 解析说明符时,如果找不到完全匹配项,require() 将尝试添加扩展名(.js、.json,最后是 .node),然后尝试解析文件夹作为模块。
  
  \When resolving a specifier, if no exact match is found, require() will try to add extensions (.js, .json, and finally .node) and then attempt to resolve folders as modules.
- 默认情况下,它不支持使用 URL 作为指定符。
  
  \It does not support URLs as specifiers by default.
加载:

\Loading:
- .json 文件会被视为 JSON 文本文件。
  
  \.json files are treated as JSON text files.
- .node 文件被解释为加载了 process.dlopen() 的编译插件模块。
  
  \.node files are interpreted as compiled addon modules loaded with process.dlopen().
- .ts、.mts 和 .cts 文件会被视为 TypeScript 文本文件。
  
  \.ts, .mts and .cts files are treated as TypeScript text files.
- 任何其他扩展名或无扩展名的文件都被视为 JavaScript 文本文件。
  
  \Files with any other extension, or without extensions, are treated as JavaScript text files.
- 只有当 ECMAScript 模块及其依赖是同步的(即它们不包含顶层 await)时,require() 才能用于从 CommonJS 模块加载 ECMAScript 模块。
  
  \require() can only be used to load ECMAScript modules from CommonJS modules if the ECMAScript module and its dependencies are synchronous (i.e. they do not contain top-level await).

当通过静态 import 语句(仅在 ES 模块中可用)或 import() 表达式(CommonJS 和 ES 模块均可用)请求模块时:

\When a module is requested via static import statements (only available in ES Modules) or import() expressions (available in both CommonJS and ES Modules):

解析:

\Resolution:
- import/import() 的解析不支持将文件夹作为模块,目录索引(例如 './startup/index.js')必须完整指定。
  
  \The resolution of import/import() does not support folders as modules, directory indexes (e.g. './startup/index.js') must be fully specified.
- 它不执行扩展名搜索。当说明符是相对或绝对的文件 URL 时,必须提供文件扩展名。
  
  \It does not perform extension searching. A file extension must be provided when the specifier is a relative or absolute file URL.
- 默认情况下,它支持使用 file:// 和 data: URL 作为指定符。
  
  \It supports file:// and data: URLs as specifiers by default.
加载:

\Loading:
- .json 文件会被视为 JSON 文本文件。导入 JSON 模块时,必须指定导入类型属性(例如 import json from './data.json' with { type: 'json' })。
  
  \.json files are treated as JSON text files. When importing JSON modules, an import type attribute is required (e.g. import json from './data.json' with { type: 'json' }).
- 如果启用了 --experimental-addon-modules,则 .node 文件会被解释为使用 process.dlopen() 加载的已编译插件模块。
  
  \.node files are interpreted as compiled addon modules loaded with process.dlopen(), if --experimental-addon-modules is enabled.
- .ts、.mts 和 .cts 文件会被视为 TypeScript 文本文件。
  
  \.ts, .mts and .cts files are treated as TypeScript text files.
- 它只接受 JavaScript 文本文件的 .js、.mjs 和 .cjs 扩展名。
  
  \It accepts only .js, .mjs, and .cjs extensions for JavaScript text files.
- .wasm 文件会被视为 WebAssembly 模块。
  
  \.wasm files are treated as WebAssembly modules.
- 任何其他文件扩展名都会导致 ERR_UNKNOWN_FILE_EXTENSION 错误。可以通过自定义钩子实现添加其他文件扩展名。
  
  \Any other file extensions will result in a ERR_UNKNOWN_FILE_EXTENSION error. Additional file extensions can be facilitated via customization hooks.
- import/import() 可用于加载 JavaScript CommonJS 模块。这样的模块通过 cjs-module-lexer 来尝试识别命名的导出,如果可以通过静态分析确定的话是可用的。
  
  \import/import() can be used to load JavaScript CommonJS modules. Such modules are passed through the cjs-module-lexer to try to identify named exports, which are available if they can be determined through static analysis.

无论模块的请求方式如何,都可以使用自定义钩子自定义解析和加载过程。

\Regardless of how a module is requested, the resolution and loading process can be customized using customization hooks.