解析算法

¥Resolution algorithm

加载 ES 模块说明符的算法通过下面的 ESM_RESOLVE 方法给出。它返回相对于 parentURL 的模块说明符的解析 URL。

¥The algorithm to load an ES module specifier is given through the ESM_RESOLVE method below. It returns the resolved URL for a module specifier relative to a parentURL.

解析算法确定模块加载的完整解析 URL 及其建议的模块格式。解析算法不确定是否可以加载已解析的 URL 协议，或者是否允许文件扩展名，而是由 Node.js 在加载阶段应用这些验证（例如，如果要求加载具有非 file:、data: 或 node: 协议的 URL。

¥The resolution algorithm determines the full resolved URL for a module load, along with its suggested module format. The resolution algorithm does not determine whether the resolved URL protocol can be loaded, or whether the file extensions are permitted, instead these validations are applied by Node.js during the load phase (for example, if it was asked to load a URL that has a protocol that is not file:, data: or node:.

该算法还尝试根据扩展名确定文件的格式（参见下面的 ESM_FILE_FORMAT 算法）。如果它不识别文件扩展名（例如，如果它不是 .mjs、.cjs 或 .json），则返回 undefined 格式，这将在加载阶段抛出。

¥The algorithm also tries to determine the format of the file based on the extension (see ESM_FILE_FORMAT algorithm below). If it does not recognize the file extension (eg if it is not .mjs, .cjs, or .json), then a format of undefined is returned, which will throw during the load phase.

ESM_FILE_FORMAT 提供了确定已解析 URL 的模块格式的算法，该算法返回任何文件的唯一模块格式。"module" 格式为 ECMAScript 模块返回，而 "commonjs" 格式用于指示通过旧版 CommonJS 加载器加载。可以在未来的更新中扩展其他格式，例如 "addon"。

¥The algorithm to determine the module format of a resolved URL is provided by ESM_FILE_FORMAT, which returns the unique module format for any file. The "module" format is returned for an ECMAScript Module, while the "commonjs" format is used to indicate loading through the legacy CommonJS loader. Additional formats such as "addon" can be extended in future updates.

在以下算法中，除非另有说明，否则所有子程序错误都将作为这些顶层程序的错误传播。

¥In the following algorithms, all subroutine errors are propagated as errors of these top-level routines unless stated otherwise.

defaultConditions 是条件环境名称数组，["node", "import"]。

¥defaultConditions is the conditional environment name array, ["node", "import"].

解析器可能会抛出以下错误：

¥The resolver can throw the following errors:

  • 无效的模块说明符：模块说明符是无效的 URL、包名称或包的子路径说明符。

    ¥Invalid Module Specifier: Module specifier is an invalid URL, package name or package subpath specifier.

  • 无效的包配置：package.json 配置无效或包含无效配置。

    ¥Invalid Package Configuration: package.json configuration is invalid or contains an invalid configuration.

  • 无效的包目标：包导出或导入为包定义了一个目标模块，该模块是无效类型或字符串目标。

    ¥Invalid Package Target: Package exports or imports define a target module for the package that is an invalid type or string target.

  • 未导出的包路径：包导出不为给定模块定义或允许包中的目标子路径。

    ¥Package Path Not Exported: Package exports do not define or permit a target subpath in the package for the given module.

  • 包导入未定义：包导入不定义说明符。

    ¥Package Import Not Defined: Package imports do not define the specifier.

  • 未找到模块：请求的包或模块不存在。

    ¥Module Not Found: The package or module requested does not exist.

  • 不支持的目录导入：解析的路径对应于一个目录，该目录不是模块导入的受支持目标。

    ¥Unsupported Directory Import: The resolved path corresponds to a directory, which is not a supported target for module imports.