模块：node:moduleAPI#>

定制钩子#>

🌐 Customization Hooks

版本历史

版本变更

v23.5.0, v22.15.0

Add support for synchronous and in-thread hooks.

v20.6.0, v18.19.0

Added initialize hook to replace globalPreload.

v18.6.0, v16.17.0

Add support for chaining loaders.

v16.12.0

Removed getFormat, getSource, transformSource, and globalPreload; added load hook and getGlobalPreload hook.

v8.8.0

新增于: v8.8.0

稳定性： 1.1 - 处于活跃开发中

目前支持两种类型的模块自定义钩子：

🌐 There are two types of module customization hooks that are currently supported:

module.register(specifier[，父级网址][, options]) 接收一个导出异步钩子函数的模块。这些函数将在一个单独的加载线程上运行。

module.registerHooks(options) 接受同步钩子函数，这些函数会在模块加载的线程上直接运行。

启用#>

🌐 Enabling

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

🌐 Module resolution and loading can be customized by:

注册一个导出一组异步钩子函数的文件，使用来自 node:module 的 register 方法，

使用 node:module 中的 registerHooks 方法注册一组同步钩子函数。

可以在应用代码运行之前使用 --import 或 --require 标志注册这些钩子：

🌐 The hooks can be registered before the application code is run by using the

--import or --require flag:

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

node --require ./register-hooks.js ./my-app.js 拷贝

// 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));拷贝

// 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 */ },

});拷贝

传递给 --import 或 --require 的文件也可以是某个依赖的导出内容：

🌐 The file passed to --import or --require can also be an export from a dependency:

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

node --require some-package/register ./my-app.js 拷贝

some-package 包含一个 "exports" 字段，用于定义 /register 导出，以映射到调用 register() 的文件，例如以下 register-hooks.js 示例。

🌐 Where some-package has an "exports" field defining the /register

export to map to a file that calls register(), like the following register-hooks.js

example.

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

🌐 Using --import or --require ensures that the hooks are registered before any

application files are imported, including the entry point of the application and for

any worker threads by default as well.

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

🌐 Alternatively, register() and registerHooks() can be called from the entry point,

though dynamic import() must be used for any ESM code that should be run after the hooks

are registered.

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');拷贝

自定义钩子将在注册后加载的任何模块以及它们通过 import 和内置 require 引用的模块上运行。通过 module.createRequire() 创建的用户 require 函数只能通过同步钩子进行自定义。

🌐 Customization hooks will run for any modules loaded later than the registration

and the modules they reference via import and the built-in require.

require function created by users using module.createRequire() can only be

customized by the synchronous hooks.

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

🌐 In this example, we are registering the http-to-https hooks, but they will

only be available for subsequently imported modules — in this case, my-app.js

and anything it references via import or built-in require in CommonJS dependencies.

如果 import('./my-app.js') 改为静态的 import './my-app.js'，应用将在注册 http-to-https 钩子之前就已经被加载。这是由于 ES 模块规范，静态导入会先从依赖树的叶子节点开始求值，然后再回到主干。在 my-app.js 内部可能还有静态导入，这些导入只有在动态导入 my-app.js 时才会被求值。

🌐 If the import('./my-app.js') had instead been a static import './my-app.js', the

app would have already been loaded before the http-to-https hooks were

registered. This due to the ES modules specification, where static imports are

evaluated from the leaves of the tree first, then back to the trunk. There can

be static imports within my-app.js, which will not be evaluated until

my-app.js is dynamically imported.

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

🌐 If synchronous hooks are used, both import, require and user require created

using createRequire() are supported.

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');拷贝

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

🌐 Finally, if all you want to do is register hooks before your app runs and you

don't want to create a separate file for that purpose, you can pass a data:

URL to --import:

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

链接#>

🌐 Chaining

可以多次调用 register：

🌐 It's possible to call register more than once:

// 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');拷贝

在这个例子中，注册的钩子将形成链。这些链以后进先出（LIFO）的顺序运行。如果 foo.mjs 和 bar.mjs 都定义了 resolve 钩子，它们将按如下方式调用（注意从右到左）：

node 默认 ← ./foo.mjs ← ./bar.mjs

（从 ./bar.mjs 开始，然后是 ./foo.mjs，最后是 Node.js 默认）。

其他所有钩子也同样适用。

🌐 In this example, the registered hooks will form chains. These chains run

last-in, first out (LIFO). If both foo.mjs and bar.mjs define a resolve

hook, they will be called like so (note the right-to-left):

node's default ← ./foo.mjs ← ./bar.mjs

(starting with ./bar.mjs, then ./foo.mjs, then the Node.js default).

The same applies to all the other hooks.

已注册的钩子也会影响 register 本身。在这个例子中，bar.mjs 将通过 foo.mjs 注册的钩子来解析和加载（因为 foo 的钩子已经被添加到链中）。这允许像使用非 JavaScript 语言编写钩子这样的操作，只要先前注册的钩子能够转译成 JavaScript。

🌐 The registered hooks also affect register itself. In this example,

bar.mjs will be resolved and loaded via the hooks registered by foo.mjs

(because foo's hooks will have already been added to the chain). This allows

for things like writing hooks in non-JavaScript languages, so long as

earlier registered hooks transpile into JavaScript.

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

🌐 The register method cannot be called from within the module that defines the

hooks.

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

🌐 Chaining of registerHooks work similarly. If synchronous and asynchronous

hooks are mixed, the synchronous hooks are always run first before the asynchronous

hooks start running, that is, in the last synchronous hook being run, its next

hook includes invocation of the asynchronous hooks.

// 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);拷贝

与模块定制钩子通信#>

🌐 Communication with module customization hooks

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

🌐 Asynchronous hooks run on a dedicated thread, separate from the main

thread that runs application code. This means mutating global variables won't

affect the other thread(s), and message channels must be used to communicate

between the threads.

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

🌐 The register method can be used to pass data to an initialize hook. The

data passed to the hook may include transferable objects like ports.

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],

});拷贝

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

🌐 Synchronous module hooks are run on the same thread where the application code is

run. They can directly mutate the globals of the context accessed by the main thread.

钩子#>

🌐 Hooks

module.register() 接受异步钩子#>

🌐 Asynchronous hooks accepted by module.register()

register 方法可用于注册导出一组钩子的模块。钩子是由 Node.js 调用的函数，用于自定义模块解析和加载过程。导出的函数必须具有特定的名称和签名，并且必须以命名导出的形式导出。

🌐 The register method can be used to register a module that exports a set of

hooks. The hooks are functions that are called by Node.js to customize the

module resolution and loading process. The exported functions must have specific

names and signatures, and they must be exported as named exports.

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.

} 拷贝

异步钩子在一个独立的线程中运行，与执行应用代码的主线程隔离。这意味着它是一个不同的字段。钩子线程可能会随时被主线程终止，因此不要依赖异步操作（如 console.log）的完成。它们默认会继承到子工作线程中。

🌐 Asynchronous hooks are run in a separate thread, isolated from the main thread where

application code runs. That means it is a different realm. The hooks thread

may be terminated by the main thread at any time, so do not depend on

asynchronous operations (like console.log) to complete. They are inherited into

child workers by default.

module.registerHooks() 接受同步钩子#>

🌐 Synchronous hooks accepted by module.registerHooks()

新增于: v23.5.0, v22.15.0

稳定性： 1.1 - 处于活跃开发中

module.registerHooks() 方法接受同步钩子函数。initialize() 不被支持也不必要，因为钩子实现者可以在调用 module.registerHooks() 之前直接运行初始化代码。

🌐 The module.registerHooks() method accepts synchronous hook functions.

initialize() is not supported nor necessary, as the hook implementer

can simply run the initialization code directly before the call to

module.registerHooks().

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.

} 拷贝

同步钩子在相同的线程和加载模块的相同 字段 中运行。与异步钩子不同，它们默认不会继承到子工作线程中，不过如果钩子是通过 --import 或 --require 预加载的文件注册的，子工作线程可以通过 process.execArgv 继承预加载的脚本。详情见 Worker 的文档。

🌐 Synchronous hooks are run in the same thread and the same realm where the modules

are loaded. Unlike the asynchronous hooks they are not inherited into child worker

threads by default, though if the hooks are registered using a file preloaded by

--import or --require, child worker threads can inherit the preloaded scripts

via process.execArgv inheritance. See the documentation of Worker for detail.

在同步钩子中，用户可以预期 console.log() 的执行方式与他们在模块代码中预期 console.log() 的执行方式相同。

🌐 In synchronous hooks, users can expect console.log() to complete in the same way that

they expect console.log() in module code to complete.

钩子的约定#>

🌐 Conventions of hooks

Hooks 是 链条 的一部分，即使该链只包含一个自定义（用户提供的）hook 和始终存在的默认 hook。Hook 函数是嵌套的：每个函数必须总是返回一个普通对象，而链式调用的发生是因为每个函数调用了 next()，它是对后续加载器的 hook 的引用（按后进先出顺序）。

返回缺少必需属性的值的钩子会触发异常。一个钩子如果没有调用 next() 并且也没有返回 shortCircuit: true，同样会触发异常。这些错误是为了帮助防止链条意外中断。从钩子返回 shortCircuit: true 表示链条在你的钩子处故意结束。

initialize()#>

新增于: v20.6.0, v18.19.0

稳定性： 1.2 - 发布候选版

data 来自 register(loader, import.meta.url, { data }) 的数据。

initialize 钩子仅被 register 接受。registerHooks() 不支持也不需要它，因为同步钩子的初始化可以在调用 registerHooks() 之前直接执行。

🌐 The initialize hook is only accepted by register. registerHooks() does

not support nor need it since initialization done for synchronous hooks can be run

directly before the call to registerHooks().

initialize 钩子提供了一种方式，可以定义一个自定义函数，当 hooks 模块初始化时，该函数将在 hooks 线程中运行。当通过 register 注册 hooks 模块时，初始化就会发生。

🌐 The initialize hook provides a way to define a custom function that runs in

the hooks thread when the hooks module is initialized. Initialization happens

when the hooks module is registered via register.

这个钩子可以从 register 调用接收数据，包括端口和其他可传递对象。initialize 的返回值可以是一个 ，在这种情况下，它将在主应用线程执行恢复之前被等待。

🌐 This hook can receive data from a register invocation, including

ports and other transferable objects. The return value of initialize can be a

, in which case it will be awaited before the main application thread

execution resumes.

模块定制代码：

🌐 Module customization code:

// path-to-my-hooks.js

export async function initialize({ number, port }) {

port.postMessage(`increment: ${number + 1}`);

} 拷贝

调用者代码：

🌐 Caller code:

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],

});拷贝

resolve(specifier, context, nextResolve)#>

版本历史

版本变更

v23.5.0, v22.15.0

Add support for synchronous and in-thread hooks.

v21.0.0, v20.10.0, v18.19.0

The property context.importAssertions is replaced with context.importAttributes. Using the old name is still supported and will emit an experimental warning.

v18.6.0, v16.17.0

Add support for chaining resolve hooks. Each hook must either call nextResolve() or include a shortCircuit property set to true in its return.

v17.1.0, v16.14.0

Add support for import assertions.

specifier

context