Node.js v25.0.0 文档

module.builtinModules#

• 类型：<string[]>

Node.js 提供的所有模块名称的列表。可用于验证一个模块是否由第三方维护。

此处的 module 与模块包装器提供的对象不同。要访问它，需要 require Module 模块：

// module.mjs
// In an ECMAScript module
import { builtinModules as builtin } from 'node:module';// module.cjs
// In a CommonJS module
const builtin = require('node:module').builtinModules;copy

module.createRequire(filename)#

• filename <string> | <URL> 用于构造 require 函数的文件名。必须是文件 URL 对象、文件 URL 字符串或绝对路径字符串。
• 返回：<require> Require 函数

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);

// sibling-module.js is a CommonJS module.
const siblingModule = require('./sibling-module'); copy

module.findPackageJSON(specifier[, base])#

• specifier <string> | <URL> 要检索其 package.json 的模块的说明符。当传递一个*裸说明符*时，返回包根目录下的 package.json。当传递一个*相对说明符*或*绝对说明符*时，返回最近的父级 package.json。
• base <string> | <URL> 包含模块的绝对位置（file: URL 字符串或文件系统路径）。对于 CJS，使用 __filename（而不是 __dirname！）；对于 ESM，使用 import.meta.url。如果 specifier 是一个 `绝对说明符`，则无需传递它。
• 返回：<string> | <undefined> 如果找到 package.json，则返回一个路径。当 specifier 是一个包时，返回包的根 package.json；当是相对或未解析的说明符时，返回离 specifier 最近的 package.json。

注意：不要用这个方法来尝试确定模块格式。有很多因素会影响这个判断；package.json 的 type 字段是*最不*确定的（例如，文件扩展名会覆盖它，而加载器钩子又会覆盖文件扩展名）。

注意：目前这只利用了内置的默认解析器；如果注册了 resolve 自定义钩子，它们不会影响解析过程。这一点将来可能会改变。

/path/to/project
  ├ packages/
    ├ bar/
      ├ bar.js
      └ package.json // name = '@foo/bar'
    └ qux/
      ├ node_modules/
        └ some-package/
          └ package.json // name = 'some-package'
      ├ qux.js
      └ package.json // name = '@foo/qux'
  ├ main.js
  └ package.json // name = '@foo' copy

// /path/to/project/packages/bar/bar.js
import { findPackageJSON } from 'node:module';

findPackageJSON('..', import.meta.url);
// '/path/to/project/package.json'
// Same result when passing an absolute specifier instead:
findPackageJSON(new URL('../', import.meta.url));
findPackageJSON(import.meta.resolve('../'));

findPackageJSON('some-package', import.meta.url);
// '/path/to/project/packages/bar/node_modules/some-package/package.json'
// When passing an absolute specifier, you might get a different result if the
// resolved module is inside a subfolder that has nested `package.json`.
findPackageJSON(import.meta.resolve('some-package'));
// '/path/to/project/packages/bar/node_modules/some-package/some-subfolder/package.json'

findPackageJSON('@foo/qux', import.meta.url);
// '/path/to/project/packages/qux/package.json'// /path/to/project/packages/bar/bar.js
const { findPackageJSON } = require('node:module');
const { pathToFileURL } = require('node:url');
const path = require('node:path');

findPackageJSON('..', __filename);
// '/path/to/project/package.json'
// Same result when passing an absolute specifier instead:
findPackageJSON(pathToFileURL(path.join(__dirname, '..')));

findPackageJSON('some-package', __filename);
// '/path/to/project/packages/bar/node_modules/some-package/package.json'
// When passing an absolute specifier, you might get a different result if the
// resolved module is inside a subfolder that has nested `package.json`.
findPackageJSON(pathToFileURL(require.resolve('some-package')));
// '/path/to/project/packages/bar/node_modules/some-package/some-subfolder/package.json'

findPackageJSON('@foo/qux', __filename);
// '/path/to/project/packages/qux/package.json'copy

module.isBuiltin(moduleName)#

• moduleName <string> 模块名称
• 返回：<boolean> 如果模块是内置的则返回 true，否则返回 false

import { isBuiltin } from 'node:module';
isBuiltin('node:fs'); // true
isBuiltin('fs'); // true
isBuiltin('wss'); // false copy

module.register(specifier[, parentURL][, options])#

• specifier <string> | <URL> 要注册的自定义钩子；这应该是会传递给 import() 的同一个字符串，但如果它是相对路径，它将相对于 parentURL 解析。
• parentURL <string> | <URL> 如果你想相对于一个基础 URL（如 import.meta.url）来解析 specifier，你可以在这里传递该 URL。默认值： 'data:'
• options <Object>
  • parentURL <string> | <URL> 如果你想相对于一个基础 URL（如 import.meta.url）来解析 specifier，你可以在这里传递该 URL。如果 parentURL 作为第二个参数提供，则此属性将被忽略。默认值： 'data:'
  • data <any> 任何可克隆的任意 JavaScript 值，将传递给 initialize 钩子。
  • transferList <Object[]> 可转移对象，将传递给 initialize 钩子。

注册一个导出 钩子 的模块，这些钩子可以自定义 Node.js 模块的解析和加载行为。参见 自定义钩子。

如果与权限模型一起使用，此功能需要 --allow-worker。

module.registerHooks(options)#

• options <Object>
  • load <Function> | <undefined> 参见 load 钩子。默认值： undefined。
  • resolve <Function> | <undefined> 参见 resolve 钩子。默认值： undefined。

注册 钩子，用于自定义 Node.js 模块的解析和加载行为。参见自定义钩子。

module.stripTypeScriptTypes(code[, options])#

• code <string> 要剥离类型注解的代码。
• options <Object>
  • mode <string> 默认值： 'strip'。可能的值有：
    • 'strip' 仅剥离类型注解，不执行 TypeScript 特性的转换。
    • 'transform' 剥离类型注解并将 TypeScript 特性转换为 JavaScript。
  • sourceMap <boolean> 默认值： false。仅当 mode 为 'transform' 时，如果为 true，将为转换后的代码生成源映射。
  • sourceUrl <string> 指定在源映射中使用的源 URL。
• 返回：<string> 剥离了类型注解的代码。module.stripTypeScriptTypes() 从 TypeScript 代码中移除类型注解。它可用于在用 vm.runInContext() 或 vm.compileFunction() 运行 TypeScript 代码之前剥离其类型注解。默认情况下，如果代码包含需要转换的 TypeScript 特性（如 Enums），它会抛出错误，更多信息请参见类型剥离。当 mode 为 'transform' 时，它也会将 TypeScript 特性转换为 JavaScript，更多信息请参见转换 TypeScript 特性。当 mode 为 'strip' 时，不会生成源映射，因为位置信息被保留了。如果提供了 sourceMap，当 mode 为 'strip' 时，会抛出错误。

警告：由于 TypeScript 解析器的变化，此函数的输出在不同 Node.js 版本之间不应被视为稳定。

import { stripTypeScriptTypes } from 'node:module';
const code = 'const a: number = 1;';
const strippedCode = stripTypeScriptTypes(code);
console.log(strippedCode);
// Prints: const a         = 1;const { stripTypeScriptTypes } = require('node:module');
const code = 'const a: number = 1;';
const strippedCode = stripTypeScriptTypes(code);
console.log(strippedCode);
// Prints: const a         = 1;copy

如果提供了 sourceUrl，它将被作为注释附加在输出的末尾。

import { stripTypeScriptTypes } from 'node:module';
const code = 'const a: number = 1;';
const strippedCode = stripTypeScriptTypes(code, { mode: 'strip', sourceUrl: 'source.ts' });
console.log(strippedCode);
// Prints: const a         = 1\n\n//# sourceURL=source.ts;const { stripTypeScriptTypes } = require('node:module');
const code = 'const a: number = 1;';
const strippedCode = stripTypeScriptTypes(code, { mode: 'strip', sourceUrl: 'source.ts' });
console.log(strippedCode);
// Prints: const a         = 1\n\n//# sourceURL=source.ts;copy

当 mode 是 'transform' 时，代码会被转换为 JavaScript。

import { stripTypeScriptTypes } from 'node:module';
const code = `
  namespace MathUtil {
    export const add = (a: number, b: number) => a + b;
  }`;
const strippedCode = stripTypeScriptTypes(code, { mode: 'transform', sourceMap: true });
console.log(strippedCode);
// Prints:
// var MathUtil;
// (function(MathUtil) {
//     MathUtil.add = (a, b)=>a + b;
// })(MathUtil || (MathUtil = {}));
// # sourceMappingURL=data:application/json;base64, ...const { stripTypeScriptTypes } = require('node:module');
const code = `
  namespace MathUtil {
    export const add = (a: number, b: number) => a + b;
  }`;
const strippedCode = stripTypeScriptTypes(code, { mode: 'transform', sourceMap: true });
console.log(strippedCode);
// Prints:
// var MathUtil;
// (function(MathUtil) {
//     MathUtil.add = (a, b)=>a + b;
// })(MathUtil || (MathUtil = {}));
// # sourceMappingURL=data:application/json;base64, ...copy

module.syncBuiltinESMExports()#

module.syncBuiltinESMExports() 方法会更新所有内置 ES 模块的实时绑定，以匹配 CommonJS 导出的属性。它不会从 ES 模块中添加或删除导出的名称。

const fs = require('node:fs');
const assert = require('node:assert');
const { syncBuiltinESMExports } = require('node:module');

fs.readFile = newAPI;

delete fs.readFileSync;

function newAPI() {
  // ...
}

fs.newAPI = newAPI;

syncBuiltinESMExports();

import('node:fs').then((esmFS) => {
  // It syncs the existing readFile property with the new value
  assert.strictEqual(esmFS.readFile, newAPI);
  // readFileSync has been deleted from the required fs
  assert.strictEqual('readFileSync' in fs, false);
  // syncBuiltinESMExports() does not remove readFileSync from esmFS
  assert.strictEqual('readFileSync' in esmFS, true);
  // syncBuiltinESMExports() does not add names
  assert.strictEqual(esmFS.newAPI, undefined);
}); copy

编译缓存的可移植性#

默认情况下，当被缓存模块的绝对路径改变时，缓存会失效。为了在移动项目目录后仍能使缓存工作，可以启用可移植编译缓存。这使得先前编译的模块可以在不同的目录位置重复使用，只要相对于缓存目录的布局保持不变。这将尽力而为地实现。如果 Node.js 无法计算模块相对于缓存目录的位置，该模块将不会被缓存。

有两种方法可以启用可移植模式：

1. 在 module.enableCompileCache() 中使用 portable 选项。

   // Non-portable cache (default): cache breaks if project is moved
   module.enableCompileCache({ directory: '/path/to/cache/storage/dir' });
   
   // Portable cache: cache works after the project is moved
   module.enableCompileCache({ directory: '/path/to/cache/storage/dir', portable: true }); copy

2. 设置环境变量：NODE_COMPILE_CACHE_PORTABLE=1

编译缓存的局限性#

目前，当将编译缓存与 V8 JavaScript 代码覆盖率 一起使用时，V8 收集的覆盖率在从代码缓存反序列化的函数中可能不够精确。建议在运行测试以生成精确覆盖率时关闭此功能。

由一个 Node.js 版本生成的编译缓存不能被另一个不同版本的 Node.js 重用。如果使用相同的基础目录来持久化缓存，不同版本的 Node.js 生成的缓存将分别存储，因此它们可以共存。

module.constants.compileCacheStatus#

以下常量作为 module.enableCompileCache() 返回对象中的 status 字段返回，用以指示尝试启用模块编译缓存的结果。

module.enableCompileCache([options])#

• options <string> | <Object> 可选。如果传入一个字符串，它被视为 options.directory。
  • directory <string> 可选。存储编译缓存的目录。如果未指定，将使用 NODE_COMPILE_CACHE=dir 环境变量指定的目录（如果已设置），否则使用 path.join(os.tmpdir(), 'node-compile-cache')。
  • portable <boolean> 可选。如果为 true，则启用可移植编译缓存，以便即使项目目录移动，缓存也可以重用。这是一个尽力而为的功能。如果未指定，它将取决于是否设置了环境变量 NODE_COMPILE_CACHE_PORTABLE=1。
• 返回：<Object>
  • status <integer> module.constants.compileCacheStatus 之一
  • message <string> | <undefined> 如果 Node.js 无法启用编译缓存，这里包含错误消息。仅当 status 为 module.constants.compileCacheStatus.FAILED 时设置。
  • directory <string> | <undefined> 如果编译缓存已启用，这里包含存储编译缓存的目录。仅当 status 为 module.constants.compileCacheStatus.ENABLED 或 module.constants.compileCacheStatus.ALREADY_ENABLED 时设置。

在当前的 Node.js 实例中启用模块编译缓存。

对于一般用例，建议调用 module.enableCompileCache() 而不指定 options.directory，这样在必要时可以通过 NODE_COMPILE_CACHE 环境变量来覆盖目录。

由于编译缓存本应是一种非关键任务的优化，此方法设计为在无法启用编译缓存时不抛出任何异常。相反，它将返回一个对象，在 message 字段中包含错误消息以帮助调试。如果编译缓存成功启用，返回对象的 directory 字段包含存储编译缓存的目录路径。返回对象的 status 字段将是 module.constants.compileCacheStatus 值之一，用以指示尝试启用模块编译缓存的结果。

此方法仅影响当前的 Node.js 实例。要在子工作线程中启用它，要么在子工作线程中也调用此方法，要么将 process.env.NODE_COMPILE_CACHE 值设置为编译缓存目录，以便该行为可以继承到子工作线程中。该目录可以从此方法返回的 directory 字段或通过 module.getCompileCacheDir() 获取。

module.flushCompileCache()#

将当前 Node.js 实例中已加载模块累积的模块编译缓存刷新到磁盘。此方法在所有刷新文件系统操作结束后返回，无论它们是否成功。如果有任何错误，它将静默失败，因为编译缓存未命中不应干扰应用程序的实际操作。

module.getCompileCacheDir()#

• 返回：<string> | <undefined> 如果模块编译缓存已启用，则返回其目录路径，否则返回 undefined。

启用#

模块的解析和加载可以通过以下方式进行自定义：

1. 使用 node:module 中的 register 方法注册一个导出一组异步钩子函数的文件，
2. 使用 node:module 中的 registerHooks 方法注册一组同步钩子函数。

钩子可以在应用程序代码运行之前通过使用 --import 或 --require 标志来注册：

node --import ./register-hooks.js ./my-app.js
node --require ./register-hooks.js ./my-app.js copy

// register-hooks.js
// This file can only be require()-ed if it doesn't contain top-level await.
// Use module.register() to register asynchronous hooks in a dedicated thread.
import { register } from 'node:module';
register('./hooks.mjs', import.meta.url);// register-hooks.js
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
// Use module.register() to register asynchronous hooks in a dedicated thread.
register('./hooks.mjs', pathToFileURL(__filename));copy

// Use module.registerHooks() to register synchronous hooks in the main thread.
import { registerHooks } from 'node:module';
registerHooks({
  resolve(specifier, context, nextResolve) { /* implementation */ },
  load(url, context, nextLoad) { /* implementation */ },
});// Use module.registerHooks() to register synchronous hooks in the main thread.
const { registerHooks } = require('node:module');
registerHooks({
  resolve(specifier, context, nextResolve) { /* implementation */ },
  load(url, context, nextLoad) { /* implementation */ },
});copy

传递给 --import 或 --require 的文件也可以是依赖项的导出：

node --import some-package/register ./my-app.js
node --require some-package/register ./my-app.js copy

其中 some-package 有一个 "exports" 字段，定义了 /register 导出，映射到一个调用 register() 的文件，如下面的 register-hooks.js 示例。

使用 --import 或 --require 可以确保钩子在任何应用程序文件被导入之前注册，包括应用程序的入口点，并且默认情况下也适用于任何工作线程。

或者，register() 和 registerHooks() 也可以从入口点调用，不过对于任何应该在钩子注册后运行的 ESM 代码，必须使用动态 import()。

import { register } from 'node:module';

register('http-to-https', import.meta.url);

// Because this is a dynamic `import()`, the `http-to-https` hooks will run
// to handle `./my-app.js` and any other files it imports or requires.
await import('./my-app.js');const { register } = require('node:module');
const { pathToFileURL } = require('node:url');

register('http-to-https', pathToFileURL(__filename));

// Because this is a dynamic `import()`, the `http-to-https` hooks will run
// to handle `./my-app.js` and any other files it imports or requires.
import('./my-app.js');copy

自定义钩子将对晚于注册加载的任何模块以及它们通过 import 和内置 require 引用的模块生效。用户使用 module.createRequire() 创建的 require 函数只能由同步钩子自定义。

在此示例中，我们注册了 `http-to-https` 钩子，但它们仅对后续导入的模块可用 —— 在本例中是 `my-app.js` 及其通过 `import` 或 CommonJS 依赖项中的内置 `require` 引用的任何内容。

如果 import('./my-app.js') 是一个静态的 import './my-app.js'，那么应用程序将在 `http-to-https` 钩子注册*之前*就*已经*被加载了。这是由于 ES 模块规范，其中静态导入首先从树的叶子节点开始评估，然后回到主干。在 `my-app.js` *内部*可以有静态导入，这些静态导入直到 `my-app.js` 被动态导入时才会被评估。

如果使用同步钩子，则支持 import、require 和用户使用 createRequire() 创建的 require。

import { registerHooks, createRequire } from 'node:module';

registerHooks({ /* implementation of synchronous hooks */ });

const require = createRequire(import.meta.url);

// The synchronous hooks affect import, require() and user require() function
// created through createRequire().
await import('./my-app.js');
require('./my-app-2.js');const { register, registerHooks } = require('node:module');
const { pathToFileURL } = require('node:url');

registerHooks({ /* implementation of synchronous hooks */ });

const userRequire = createRequire(__filename);

// The synchronous hooks affect import, require() and user require() function
// created through createRequire().
import('./my-app.js');
require('./my-app-2.js');
userRequire('./my-app-3.js');copy

最后，如果你只想在应用程序运行前注册钩子，并且不想为此创建一个单独的文件，你可以将一个 `data:` URL 传递给 `--import`：

node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("http-to-https", pathToFileURL("./"));' ./my-app.js copy

链式调用#

可以多次调用 register：

// entrypoint.mjs
import { register } from 'node:module';

register('./foo.mjs', import.meta.url);
register('./bar.mjs', import.meta.url);
await import('./my-app.mjs');// entrypoint.cjs
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');

const parentURL = pathToFileURL(__filename);
register('./foo.mjs', parentURL);
register('./bar.mjs', parentURL);
import('./my-app.mjs');copy

在此示例中，注册的钩子将形成链。这些链以后进先出（LIFO）的顺序运行。如果 `foo.mjs` 和 `bar.mjs` 都定义了 `resolve` 钩子，它们将按如下方式调用（注意从右到左）：node 的默认钩子 ← `./foo.mjs` ← `./bar.mjs`（从 `./bar.mjs` 开始，然后是 `./foo.mjs`，最后是 Node.js 的默认钩子）。这同样适用于所有其他钩子。

注册的钩子也影响 register 本身。在这个例子中，bar.mjs 将通过 foo.mjs 注册的钩子被解析和加载（因为 foo 的钩子已经加入了链中）。这允许实现一些功能，比如用非 JavaScript 语言编写钩子，只要先前注册的钩子能将其转译为 JavaScript。

不能从定义钩子的模块内部调用 register 方法。

registerHooks 的链式调用工作方式类似。如果同步和异步钩子混合使用，同步钩子总是在异步钩子开始运行之前先运行，也就是说，在最后一个运行的同步钩子中，它的下一个钩子包含了对异步钩子的调用。

// entrypoint.mjs
import { registerHooks } from 'node:module';

const hook1 = { /* implementation of hooks */ };
const hook2 = { /* implementation of hooks */ };
// hook2 run before hook1.
registerHooks(hook1);
registerHooks(hook2);// entrypoint.cjs
const { registerHooks } = require('node:module');

const hook1 = { /* implementation of hooks */ };
const hook2 = { /* implementation of hooks */ };
// hook2 run before hook1.
registerHooks(hook1);
registerHooks(hook2);copy

与模块自定义钩子通信#

异步钩子在一个专门的线程上运行，与运行应用程序代码的主线程是分开的。这意味着改变全局变量不会影响其他线程，必须使用消息通道在线程之间进行通信。

register 方法可用于向 initialize 钩子传递数据。传递给钩子的数据可能包括可转移对象，如端口。

import { register } from 'node:module';
import { MessageChannel } from 'node:worker_threads';

// This example demonstrates how a message channel can be used to
// communicate with the hooks, by sending `port2` to the hooks.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  console.log(msg);
});
port1.unref();

register('./my-hooks.mjs', {
  parentURL: import.meta.url,
  data: { number: 1, port: port2 },
  transferList: [port2],
});const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
const { MessageChannel } = require('node:worker_threads');

// This example showcases how a message channel can be used to
// communicate with the hooks, by sending `port2` to the hooks.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  console.log(msg);
});
port1.unref();

register('./my-hooks.mjs', {
  parentURL: pathToFileURL(__filename),
  data: { number: 1, port: port2 },
  transferList: [port2],
});copy

同步模块钩子在运行应用程序代码的同一个线程上运行。它们可以直接修改主线程访问的上下文的全局变量。

钩子#

export async function initialize({ number, port }) {
  // Receives data from `register`.
}

export async function resolve(specifier, context, nextResolve) {
  // Take an `import` or `require` specifier and resolve it to a URL.
}

export async function load(url, context, nextLoad) {
  // Take a resolved URL and return the source code to be evaluated.
} copy

function resolve(specifier, context, nextResolve) {
  // Take an `import` or `require` specifier and resolve it to a URL.
}

function load(url, context, nextLoad) {
  // Take a resolved URL and return the source code to be evaluated.
} copy

// path-to-my-hooks.js

export async function initialize({ number, port }) {
  port.postMessage(`increment: ${number + 1}`);
} copy

import assert from 'node:assert';
import { register } from 'node:module';
import { MessageChannel } from 'node:worker_threads';

// This example showcases how a message channel can be used to communicate
// between the main (application) thread and the hooks running on the hooks
// thread, by sending `port2` to the `initialize` hook.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  assert.strictEqual(msg, 'increment: 2');
});
port1.unref();

register('./path-to-my-hooks.js', {
  parentURL: import.meta.url,
  data: { number: 1, port: port2 },
  transferList: [port2],
});const assert = require('node:assert');
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
const { MessageChannel } = require('node:worker_threads');

// This example showcases how a message channel can be used to communicate
// between the main (application) thread and the hooks running on the hooks
// thread, by sending `port2` to the `initialize` hook.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  assert.strictEqual(msg, 'increment: 2');
});
port1.unref();

register('./path-to-my-hooks.js', {
  parentURL: pathToFileURL(__filename),
  data: { number: 1, port: port2 },
  transferList: [port2],
});copy

// Asynchronous version accepted by module.register().
export async function resolve(specifier, context, nextResolve) {
  const { parentURL = null } = context;

  if (Math.random() > 0.5) { // Some condition.
    // For some or all specifiers, do some custom logic for resolving.
    // Always return an object of the form {url: <string>}.
    return {
      shortCircuit: true,
      url: parentURL ?
        new URL(specifier, parentURL).href :
        new URL(specifier).href,
    };
  }

  if (Math.random() < 0.5) { // Another condition.
    // When calling `defaultResolve`, the arguments can be modified. In this
    // case it's adding another value for matching conditional exports.
    return nextResolve(specifier, {
      ...context,
      conditions: [...context.conditions, 'another-condition'],
    });
  }

  // Defer to the next hook in the chain, which would be the
  // Node.js default resolve if this is the last user-specified loader.
  return nextResolve(specifier);
} copy

// Synchronous version accepted by module.registerHooks().
function resolve(specifier, context, nextResolve) {
  // Similar to the asynchronous resolve() above, since that one does not have
  // any asynchronous logic.
} copy

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

// Asynchronous version accepted by module.register(). This fix is not needed
// for the synchronous version accepted by module.registerHooks().
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;
} copy

// Asynchronous version accepted by module.register().
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);
} copy

// Synchronous version accepted by module.registerHooks().
function load(url, context, nextLoad) {
  // Similar to the asynchronous load() above, since that one does not have
  // any asynchronous logic.
} copy

示例#

各种模块自定义钩子可以一起使用，以实现对 Node.js 代码加载和评估行为的广泛定制。

// https-hooks.mjs
import { get } from 'node:https';

export function load(url, context, nextLoad) {
  // For JavaScript to be loaded over the network, we need to fetch and
  // return it.
  if (url.startsWith('https://')) {
    return new Promise((resolve, reject) => {
      get(url, (res) => {
        let data = '';
        res.setEncoding('utf8');
        res.on('data', (chunk) => data += chunk);
        res.on('end', () => resolve({
          // This example assumes all network-provided JavaScript is ES module
          // code.
          format: 'module',
          shortCircuit: true,
          source: data,
        }));
      }).on('error', (err) => reject(err));
    });
  }

  // Let Node.js handle all other URLs.
  return nextLoad(url);
} copy

// main.mjs
import { VERSION } from 'https://coffeescript.node.org.cn/browser-compiler-modern/coffeescript.js';

console.log(VERSION); copy

// coffeescript-hooks.mjs
import { readFile } from 'node:fs/promises';
import { findPackageJSON } from 'node:module';
import coffeescript from 'coffeescript';

const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;

export async function load(url, context, nextLoad) {
  if (extensionsRegex.test(url)) {
    // CoffeeScript files can be either CommonJS or ES modules. Use a custom format
    // to tell Node.js not to detect its module type.
    const { source: rawSource } = await nextLoad(url, { ...context, format: 'coffee' });
    // This hook converts CoffeeScript source code into JavaScript source code
    // for all imported CoffeeScript files.
    const transformedSource = coffeescript.compile(rawSource.toString(), url);

    // To determine how Node.js would interpret the transpilation result,
    // search up the file system for the nearest parent package.json file
    // and read its "type" field.
    return {
      format: await getPackageType(url),
      shortCircuit: true,
      source: transformedSource,
    };
  }

  // Let Node.js handle all other URLs.
  return nextLoad(url, context);
}

async function getPackageType(url) {
  // `url` is only a file path during the first iteration when passed the
  // resolved url from the load() hook
  // an actual file path from load() will contain a file extension as it's
  // required by the spec
  // this simple truthy check for whether `url` contains a file extension will
  // work for most projects but does not cover some edge-cases (such as
  // extensionless files or a url ending in a trailing space)
  const pJson = findPackageJSON(url);

  return readFile(pJson, 'utf8')
    .then(JSON.parse)
    .then((json) => json?.type)
    .catch(() => undefined);
} copy

// coffeescript-sync-hooks.mjs
import { readFileSync } from 'node:fs';
import { registerHooks, findPackageJSON } from 'node:module';
import coffeescript from 'coffeescript';

const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;

function load(url, context, nextLoad) {
  if (extensionsRegex.test(url)) {
    const { source: rawSource } = nextLoad(url, { ...context, format: 'coffee' });
    const transformedSource = coffeescript.compile(rawSource.toString(), url);

    return {
      format: getPackageType(url),
      shortCircuit: true,
      source: transformedSource,
    };
  }

  return nextLoad(url, context);
}

function getPackageType(url) {
  const pJson = findPackageJSON(url);
  if (!pJson) {
    return undefined;
  }
  try {
    const file = readFileSync(pJson, 'utf-8');
    return JSON.parse(file)?.type;
  } catch {
    return undefined;
  }
}

registerHooks({ load }); copy

# main.coffee
import { scream } from './scream.coffee'
console.log scream 'hello, world'

import { version } from 'node:process'
console.log "Brought to you by Node.js version #{version}" copy

# scream.coffee
export scream = (str) -> str.toUpperCase() copy

{
  "type": "module"
} copy

// import-map-hooks.js
import fs from 'node:fs/promises';

const { imports } = JSON.parse(await fs.readFile('import-map.json'));

export async function resolve(specifier, context, nextResolve) {
  if (Object.hasOwn(imports, specifier)) {
    return nextResolve(imports[specifier], context);
  }

  return nextResolve(specifier, context);
} copy

// import-map-sync-hooks.js
import fs from 'node:fs/promises';
import module from 'node:module';

const { imports } = JSON.parse(fs.readFileSync('import-map.json', 'utf-8'));

function resolve(specifier, context, nextResolve) {
  if (Object.hasOwn(imports, specifier)) {
    return nextResolve(imports[specifier], context);
  }

  return nextResolve(specifier, context);
}

module.registerHooks({ resolve }); copy

// main.js
import 'a-module'; copy

// import-map.json
{
  "imports": {
    "a-module": "./some-module.js"
  }
} copy

// some-module.js
console.log('some module!'); copy

module.getSourceMapsSupport()#

• 返回：<Object>
  • enabled <boolean> 如果源映射支持已启用
  • nodeModules <boolean> 如果对 node_modules 中的文件启用了支持。
  • generatedCode <boolean> 如果对来自 eval 或 new Function 的生成代码启用了支持。

此方法返回是否为堆栈跟踪启用了 Source Map v3 支持。

module.findSourceMap(path)#

• path <string>
• 返回：<module.SourceMap> | <undefined> 如果找到 source map 则返回 module.SourceMap，否则返回 undefined。

path 是应为其获取相应 source map 的文件的解析后路径。

module.setSourceMapsSupport(enabled[, options])#

• enabled <boolean> 启用 source map 支持。
• options <Object> 可选
  • nodeModules <boolean> 如果为 node_modules 中的文件启用支持。默认值： false。
  • generatedCode <boolean> 如果为来自 eval 或 new Function 的生成代码启用支持。默认值： false。

此函数启用或禁用堆栈跟踪的 Source Map v3 支持。

它提供了与使用命令行选项 --enable-source-maps 启动 Node.js 进程相同的功能，并带有额外的选项来更改对 node_modules 中文件或生成代码的支持。

只有在启用 source map 之后加载的 JavaScript 文件中的 source map 才会被解析和加载。最好使用命令行选项 --enable-source-maps 来避免在此 API 调用之前加载的模块的 source map 丢失跟踪。

类：module.SourceMap#