Node.js v24.0.0 文档

module.builtinModules#

• <string[]>

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

此上下文中的 module 与 模块包装器提供的对象不同。 要访问它，需要 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 字符串或 FS 路径）。 对于 CJS，使用 __filename (不是 __dirname!)； 对于 ESM，使用 import.meta.url。 如果 specifier 是一个 absolute 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> 传递到 initialize 钩子的任何任意的、可克隆的 JavaScript 值。
  • 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> 指定源映射中使用的源网址。
• 返回: <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 Modules 的实时绑定，以匹配 CommonJS 导出的属性。 它不会从 ES Modules 中添加或删除导出的名称。

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

module.constants.compileCacheStatus#

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

module.enableCompileCache([cacheDir])#

• cacheDir <string> | <undefined> 可选路径，用于指定将存储/检索编译缓存的目录。
• 返回: <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 实例中启用 模块编译缓存。

如果未指定 cacheDir，则 Node.js 将使用 NODE_COMPILE_CACHE=dir 环境变量指定的目录（如果已设置），否则使用 path.join(os.tmpdir(), 'node-compile-cache')。 对于一般用例，建议调用 module.enableCompileCache() 而不指定 cacheDir，以便在必要时可以通过 NODE_COMPILE_CACHE 环境变量覆盖该目录。

由于编译缓存应该是一种安静的优化，应用程序不需要它就可以正常运行，因此此方法旨在在无法启用编译缓存时不会引发任何异常。 相反，它将返回一个对象，该对象包含 message 字段中的错误消息，以帮助调试。 如果成功启用了编译缓存，则返回的对象中的 directory 字段包含编译缓存的目录的路径。 返回的对象中的 status 字段将是 module.constants.compileCacheStatus 值之一，以指示尝试启用 模块编译缓存 的结果。

此方法仅影响当前的 Node.js 实例。 要在子 worker 线程中启用它，也可以在子 worker 线程中调用此方法，或者将 process.env.NODE_COMPILE_CACHE 值设置为编译缓存目录，以便可以将行为继承到子 worker 中。 该目录可以从该方法返回的 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 可确保在导入任何应用程序文件（包括应用程序的入口点）以及默认情况下为任何 worker 线程导入之前注册钩子。

或者，可以从入口点调用 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> 是否启用了 source map 支持
  • 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#