load(url, context, nextLoad)

• url <string> resolve 链返回的 URL

  ¥url <string> The URL returned by the resolve chain

• context <Object>

  • conditions <string[]> 相关 package.json 的导出条件

    ¥conditions <string[]> Export conditions of the relevant package.json

  • format <string> | <null> | <undefined> resolve 钩子链可选提供的格式

    ¥format <string> | <null> | <undefined> The format optionally supplied by the resolve hook chain

  • importAttributes <Object>

• nextLoad <Function> 链中后续的 load 钩子，或者用户提供的最后一个 load 钩子之后的 Node.js 默认 load 钩子

  ¥nextLoad <Function> The subsequent load hook in the chain, or the Node.js default load hook after the last user-supplied load hook

  • url <string>

  • context <Object>

• 返回：<Object>

  ¥Returns: <Object>

  • format <string>

  • shortCircuit <undefined> | <boolean> 此钩子打算终止 load 钩子链的信号。默认值：false

    ¥shortCircuit <undefined> | <boolean> A signal that this hook intends to terminate the chain of load hooks. Default: false

  • source <string> | <ArrayBuffer> | <TypedArray> Node.js 评估的来源

    ¥source <string> | <ArrayBuffer> | <TypedArray> The source for Node.js to evaluate

load 钩子提供了一种方式来定义确定网址应如何解释、检索、以及解析的自定义方法。它还负责验证导入断言。

¥The load hook provides a way to define a custom method of determining how a URL should be interpreted, retrieved, and parsed. It is also in charge of validating the import assertion.

format 的最终值必须是以下之一：

¥The final value of format must be one of the following:

format	描述	load 返回的 source 可接受的类型
'builtin'	加载 Node.js 内置模块	不适用
'commonjs'	加载 Node.js CommonJS 模块	{ string, ArrayBuffer, TypedArray, null, undefined }
'json'	加载 JSON 文件	{ string, ArrayBuffer, TypedArray }
'module'	加载 ES 模块	{ string, ArrayBuffer, TypedArray }
'wasm'	加载 WebAssembly 模块	{ ArrayBuffer, TypedArray }

source 的值对于类型 'builtin' 被忽略，因为目前无法替换 Node.js 内置（核心）模块的值。

¥The value of source is ignored for type 'builtin' because currently it is not possible to replace the value of a Node.js builtin (core) module.

省略 source 与为 'commonjs' 提供 source 具有非常不同的效果：

¥Omitting vs providing a source for 'commonjs' has very different effects:

• 当提供了 source 时，来自该模块的所有 require 调用都将由具有已注册 resolve 和 load 钩子的 ESM 加载程序处理；来自该模块的所有 require.resolve 调用都将由具有已注册 resolve 钩子的 ESM 加载程序处理；只有 CommonJS API 的子集可用（例如，没有 require.extensions、没有 require.cache、没有 require.resolve.paths），并且 CommonJS 模块加载器上的猴子修补将不适用。

  ¥When a source is provided, all require calls from this module will be processed by the ESM loader with registered resolve and load hooks; all require.resolve calls from this module will be processed by the ESM loader with registered resolve hooks; only a subset of the CommonJS API will be available (e.g. no require.extensions, no require.cache, no require.resolve.paths) and monkey-patching on the CommonJS module loader will not apply.

• 如果 source 未定义或 null，它将由 CommonJS 模块加载器处理，并且 require/require.resolve 调用将不会通过注册的钩子。nullish source 的这种行为是暂时的 - 将来将不再支持 nullish source。

  ¥If source is undefined or null, it will be handled by the CommonJS module loader and require/require.resolve calls will not go through the registered hooks. This behavior for nullish source is temporary — in the future, nullish source will not be supported.

当 node 与 --experimental-default-type=commonjs 一起运行时，Node.js 内部 load 实现（即 load 链中最后一个钩子的 next 的值）在 format 为 'commonjs' 时为 source 返回 null，以实现向后兼容性。下面是一个选择使用非默认行为的示例钩子：

¥When node is run with --experimental-default-type=commonjs, the Node.js internal load implementation, which is the value of next for the last hook in the load chain, returns null for source when format is 'commonjs' for backward compatibility. Here is an example hook that would opt-in to using the non-default behavior:

import { readFile } from 'node:fs/promises';

export async function load(url, context, nextLoad) {
  const result = await nextLoad(url, context);
  if (result.format === 'commonjs') {
    result.source ??= await readFile(new URL(result.responseURL ?? url));
  }
  return result;
} 拷贝

警告：ESM load 钩子和来自 CommonJS 模块的命名空间导出不兼容。尝试将它们一起使用将导致导入的对象为空。这可能会在未来得到解决。

¥Warning: The ESM load hook and namespaced exports from CommonJS modules are incompatible. Attempting to use them together will result in an empty object from the import. This may be addressed in the future.

这些类型都对应于 ECMAScript 中定义的类。

¥These types all correspond to classes defined in ECMAScript.

• 特定的 ArrayBuffer 对象是 SharedArrayBuffer。

  ¥The specific ArrayBuffer object is a SharedArrayBuffer.

• 特定的 TypedArray 对象是 Uint8Array。

  ¥The specific TypedArray object is a Uint8Array.

如果基于文本的格式（即 'json'、'module'）的源值不是字符串，则使用 util.TextDecoder 将其转换为字符串。

¥If the source value of a text-based format (i.e., 'json', 'module') is not a string, it is converted to a string using util.TextDecoder.

load 钩子提供了一种定义自定义方法来检索已解析 URL 的源代码的方法。这将允许加载器潜在地避免从磁盘读取文件。它还可以用于将无法识别的格式映射到支持的格式，例如 yaml 到 module。

¥The load hook provides a way to define a custom method for retrieving the source code of a resolved URL. This would allow a loader to potentially avoid reading files from disk. It could also be used to map an unrecognized format to a supported one, for example yaml to module.

export async function load(url, context, nextLoad) {
  const { format } = context;

  if (Math.random() > 0.5) { // Some condition
    /*
      For some or all URLs, do some custom logic for retrieving the source.
      Always return an object of the form {
        format: <string>,
        source: <string|buffer>,
      }.
    */
    return {
      format,
      shortCircuit: true,
      source: '...',
    };
  }

  // Defer to the next hook in the chain.
  return nextLoad(url);
} 拷贝

在更高级的场景中，这也可用于将不受支持的来源转换为受支持的来源（请参阅下面的 示例）。

¥In a more advanced scenario, this can also be used to transform an unsupported source to a supported one (see Examples below).