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.org/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#