Node.js v24.0.0 文档

启用#

Node.js 有两个模块系统：CommonJS 模块和 ECMAScript 模块。

默认情况下，Node.js 会将以下内容视为 CommonJS 模块

• 具有 .cjs 扩展名的文件；

• 当最近的父 package.json 文件包含一个值为 "commonjs" 的顶级字段 "type" 时，具有 .js 扩展名的文件。

• 当最近的父 package.json 文件不包含顶级字段 "type"，或者任何父文件夹中都没有 package.json 时，具有 .js 扩展名或没有扩展名的文件；除非该文件包含只有将其评估为 ES 模块才会没有错误的语法。 包作者应包含 "type" 字段，即使在所有源都是 CommonJS 的包中也是如此。 显式声明包的 type 将使构建工具和加载器更容易确定包中的文件应该如何解释。

• 扩展名不是 .mjs、.cjs、.json、.node 或 .js 的文件（当最近的父 package.json 文件包含一个值为 "module" 的顶级字段 "type" 时，这些文件只有通过 require() 包含时才会被识别为 CommonJS 模块，而不是用作程序的命令行入口点）。

有关更多详细信息，请参阅 确定模块系统。

调用 require() 总是使用 CommonJS 模块加载器。 调用 import() 总是使用 ECMAScript 模块加载器。

访问主模块#

当直接从 Node.js 运行文件时，require.main 设置为其 module。 这意味着可以通过测试 require.main === module 来确定文件是否已直接运行。

对于文件 foo.js，如果通过 node foo.js 运行，这将是 true，但如果通过 require('./foo') 运行，则为 false。

当入口点不是 CommonJS 模块时，require.main 是 undefined，并且无法访问主模块。

包管理器提示#

Node.js require() 函数的语义设计得足够通用，可以支持合理的目录结构。 诸如 dpkg、rpm 和 npm 之类的包管理器程序有望能够从 Node.js 模块构建本机包而无需修改。

在下面，我们给出了一个可能有效的建议目录结构

假设我们希望将文件夹 /usr/lib/node/<some-package>/<some-version> 包含特定版本的包的内容。

包可以相互依赖。 为了安装包 foo，可能需要安装特定版本的包 bar。 bar 包本身可能具有依赖项，并且在某些情况下，这些依赖项甚至可能冲突或形成循环依赖项。

因为 Node.js 会查找它加载的任何模块的 realpath（也就是说，它会解析符号链接），然后在 node_modules 文件夹中查找它们的依赖项，所以这种情况可以通过以下架构来解决

• /usr/lib/node/foo/1.2.3/：foo 包的内容，版本 1.2.3。
• /usr/lib/node/bar/4.3.2/：foo 依赖的 bar 包的内容。
• /usr/lib/node/foo/1.2.3/node_modules/bar：指向 /usr/lib/node/bar/4.3.2/ 的符号链接。
• /usr/lib/node/bar/4.3.2/node_modules/*：指向 bar 依赖的包的符号链接。

因此，即使遇到循环，或者存在依赖项冲突，每个模块都能够获得它可以使用的依赖项的版本。

当 foo 包中的代码执行 require('bar') 时，它将获得符号链接到 /usr/lib/node/foo/1.2.3/node_modules/bar 的版本。 然后，当 bar 包中的代码调用 require('quux') 时，它将获得符号链接到 /usr/lib/node/bar/4.3.2/node_modules/quux 的版本。

此外，为了使模块查找过程更加优化，我们可以将包放在 /usr/lib/node_modules/<name>/<version> 中，而不是直接放在 /usr/lib/node 中。 然后 Node.js 将不会费心在 /usr/node_modules 或 /node_modules 中查找缺失的依赖项。

为了使模块可用于 Node.js REPL，将 /usr/lib/node_modules 文件夹添加到 $NODE_PATH 环境变量也可能很有用。 由于使用 node_modules 文件夹的模块查找都是相对的，并且基于对 require() 进行调用的文件的实际路径，因此包本身可以位于任何位置。

使用 require() 加载 ECMAScript 模块#

.mjs 扩展名保留给 ECMAScript 模块。有关哪些文件被解析为 ECMAScript 模块的更多信息，请参阅确定模块系统部分。

require() 仅支持加载满足以下要求的 ECMAScript 模块：

• 该模块是完全同步的（不包含顶层 await）；并且
• 满足以下条件之一：
  1. 该文件具有 .mjs 扩展名。
  2. 该文件具有 .js 扩展名，并且最接近的 package.json 包含 "type": "module"。
  3. 该文件具有 .js 扩展名，最接近的 package.json 不包含 "type": "commonjs"，并且该模块包含 ES 模块语法。

如果加载的 ES 模块满足要求，则 require() 可以加载它并返回 模块命名空间对象。 在这种情况下，它类似于动态 import()，但同步运行并直接返回命名空间对象。

对于以下 ES 模块：

// distance.mjs
export function distance(a, b) { return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2); } copy

// point.mjs
export default class Point {
  constructor(x, y) { this.x = x; this.y = y; }
} copy

CommonJS 模块可以使用 require() 加载它们：

const distance = require('./distance.mjs');
console.log(distance);
// [Module: null prototype] {
//   distance: [Function: distance]
// }

const point = require('./point.mjs');
console.log(point);
// [Module: null prototype] {
//   default: [class Point],
//   __esModule: true,
// } copy

为了与现有的将 ES 模块转换为 CommonJS 的工具互操作，后者可以通过 require() 加载真实的 ES 模块，返回的命名空间将包含一个 __esModule: true 属性（如果它有一个 default 导出），以便工具生成的消费代码可以识别真实 ES 模块中的默认导出。如果命名空间已经定义了 __esModule，则不会添加此属性。此属性是实验性的，将来可能会更改。它应该只被将 ES 模块转换为 CommonJS 模块的工具使用，遵循现有的生态系统约定。直接在 CommonJS 中编写的代码应避免依赖它。

当 ES 模块同时包含命名导出和默认导出时，require() 返回的结果是 模块命名空间对象，它将默认导出放置在 .default 属性中，类似于 import() 返回的结果。要自定义 require(esm) 直接返回的内容，ES 模块可以使用字符串名称 "module.exports" 导出所需的值。

// point.mjs
export default class Point {
  constructor(x, y) { this.x = x; this.y = y; }
}

// `distance` is lost to CommonJS consumers of this module, unless it's
// added to `Point` as a static property.
export function distance(a, b) { return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2); }
export { Point as 'module.exports' } copy

const Point = require('./point.mjs');
console.log(Point); // [class Point]

// Named exports are lost when 'module.exports' is used
const { distance } = require('./point.mjs');
console.log(distance); // undefined copy

请注意，在上面的示例中，当使用 module.exports 导出名称时，命名导出将对 CommonJS 使用者丢失。为了允许 CommonJS 使用者继续访问命名导出，该模块可以确保默认导出是一个对象，并将命名导出作为属性附加到该对象上。例如，对于上面的示例，可以将 distance 作为静态方法附加到默认导出 Point 类上。

export function distance(a, b) { return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2); }

export default class Point {
  constructor(x, y) { this.x = x; this.y = y; }
  static distance = distance;
}

export { Point as 'module.exports' } copy

const Point = require('./point.mjs');
console.log(Point); // [class Point]

const { distance } = require('./point.mjs');
console.log(distance); // [Function: distance] copy

如果 require()'d 的模块包含顶层 await，或者它 import 的模块图包含顶层 await，则会抛出 ERR_REQUIRE_ASYNC_MODULE。 在这种情况下，用户应使用 import() 加载异步模块。

如果启用了 --experimental-print-required-tla，Node.js 将在评估之前评估模块，尝试找到顶层 await，并打印它们的位置以帮助用户修复它们，而不是抛出 ERR_REQUIRE_ASYNC_MODULE。

目前对使用 require() 加载 ES 模块的支持是实验性的，可以使用 --no-experimental-require-module 禁用。 要打印此功能的使用位置，请使用 --trace-require-module。

可以通过检查 process.features.require_module 是否为 true 来检测此功能。

全部汇总#

要获得在调用 require() 时将加载的确切文件名，请使用 require.resolve() 函数。

将以上所有内容放在一起，这是 require() 执行操作的伪代码中的高级算法：

require(X) from module at path Y
1. If X is a core module,
   a. return the core module
   b. STOP
2. If X begins with '/'
   a. set Y to the file system root
3. If X is equal to '.', or X begins with './', '/' or '../'
   a. LOAD_AS_FILE(Y + X)
   b. LOAD_AS_DIRECTORY(Y + X)
   c. THROW "not found"
4. If X begins with '#'
   a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))
5. LOAD_PACKAGE_SELF(X, dirname(Y))
6. LOAD_NODE_MODULES(X, dirname(Y))
7. THROW "not found"

MAYBE_DETECT_AND_LOAD(X)
1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
2. Else, if the source code of X can be parsed as ECMAScript module using
  <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
  the ESM resolver</a>,
  a. Load X as an ECMAScript module. STOP.
3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.

LOAD_AS_FILE(X)
1. If X is a file, load X as its file extension format. STOP
2. If X.js is a file,
    a. Find the closest package scope SCOPE to X.
    b. If no scope was found
      1. MAYBE_DETECT_AND_LOAD(X.js)
    c. If the SCOPE/package.json contains "type" field,
      1. If the "type" field is "module", load X.js as an ECMAScript module. STOP.
      2. If the "type" field is "commonjs", load X.js as a CommonJS module. STOP.
    d. MAYBE_DETECT_AND_LOAD(X.js)
3. If X.json is a file, load X.json to a JavaScript Object. STOP
4. If X.node is a file, load X.node as binary addon. STOP

LOAD_INDEX(X)
1. If X/index.js is a file
    a. Find the closest package scope SCOPE to X.
    b. If no scope was found, load X/index.js as a CommonJS module. STOP.
    c. If the SCOPE/package.json contains "type" field,
      1. If the "type" field is "module", load X/index.js as an ECMAScript module. STOP.
      2. Else, load X/index.js as a CommonJS module. STOP.
2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP
3. If X/index.node is a file, load X/index.node as binary addon. STOP

LOAD_AS_DIRECTORY(X)
1. If X/package.json is a file,
   a. Parse X/package.json, and look for "main" field.
   b. If "main" is a falsy value, GOTO 2.
   c. let M = X + (json main field)
   d. LOAD_AS_FILE(M)
   e. LOAD_INDEX(M)
   f. LOAD_INDEX(X) DEPRECATED
   g. THROW "not found"
2. LOAD_INDEX(X)

LOAD_NODE_MODULES(X, START)
1. let DIRS = NODE_MODULES_PATHS(START)
2. for each DIR in DIRS:
   a. LOAD_PACKAGE_EXPORTS(X, DIR)
   b. LOAD_AS_FILE(DIR/X)
   c. LOAD_AS_DIRECTORY(DIR/X)

NODE_MODULES_PATHS(START)
1. let PARTS = path split(START)
2. let I = count of PARTS - 1
3. let DIRS = []
4. while I >= 0,
   a. if PARTS[I] = "node_modules", GOTO d.
   b. DIR = path join(PARTS[0 .. I] + "node_modules")
   c. DIRS = DIR + DIRS
   d. let I = I - 1
5. return DIRS + GLOBAL_FOLDERS

LOAD_PACKAGE_IMPORTS(X, DIR)
1. Find the closest package scope SCOPE to DIR.
2. If no scope was found, return.
3. If the SCOPE/package.json "imports" is null or undefined, return.
4. If `--experimental-require-module` is enabled
  a. let CONDITIONS = ["node", "require", "module-sync"]
  b. Else, let CONDITIONS = ["node", "require"]
5. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
  CONDITIONS) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH).

LOAD_PACKAGE_EXPORTS(X, DIR)
1. Try to interpret X as a combination of NAME and SUBPATH where the name
   may have a @scope/ prefix and the subpath begins with a slash (`/`).
2. If X does not match this pattern or DIR/NAME/package.json is not a file,
   return.
3. Parse DIR/NAME/package.json, and look for "exports" field.
4. If "exports" is null or undefined, return.
5. If `--experimental-require-module` is enabled
  a. let CONDITIONS = ["node", "require", "module-sync"]
  b. Else, let CONDITIONS = ["node", "require"]
6. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
   `package.json` "exports", CONDITIONS) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
7. RESOLVE_ESM_MATCH(MATCH)

LOAD_PACKAGE_SELF(X, DIR)
1. Find the closest package scope SCOPE to DIR.
2. If no scope was found, return.
3. If the SCOPE/package.json "exports" is null or undefined, return.
4. If the SCOPE/package.json "name" is not the first segment of X, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
   "." + X.slice("name".length), `package.json` "exports", ["node", "require"])
   <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)

RESOLVE_ESM_MATCH(MATCH)
1. let RESOLVED_PATH = fileURLToPath(MATCH)
2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
   format. STOP
3. THROW "not found" copy

缓存#

模块在第一次加载后会被缓存。这意味着（除其他事项外）每次调用 require('foo') 都会获得完全相同的对象返回（如果它解析为相同的文件）。

如果未修改 require.cache，则多次调用 require('foo') 不会导致模块代码多次执行。这是一个重要的功能。有了它，可以返回“部分完成”的对象，从而即使在导致循环时也可以加载传递依赖项。

要使模块多次执行代码，请导出一个函数并调用该函数。

内置模块#

Node.js 有几个编译到二进制文件中的模块。 这些模块将在本文档的其他地方进行更详细的描述。

内置模块在 Node.js 源代码中定义，位于 lib/ 文件夹中。

可以使用 node: 前缀标识内置模块，在这种情况下，它会绕过 require 缓存。例如，即使存在具有该名称的 require.cache 条目，require('node:http') 始终会返回内置的 HTTP 模块。

如果将某些内置模块的标识符传递给 require()，则始终会优先加载这些模块。例如，即使存在具有该名称的文件，require('http') 始终会返回内置的 HTTP 模块。

所有内置模块的列表可以从 module.builtinModules 中检索。 这些模块全部列出，不带 node: 前缀，除非那些强制使用此类前缀的模块（如下一节所述）。

循环#

当存在循环 require() 调用时，模块在返回时可能尚未完成执行。

考虑这种情况：

a.js:

console.log('a starting');
exports.done = false;
const b = require('./b.js');
console.log('in a, b.done = %j', b.done);
exports.done = true;
console.log('a done'); copy

b.js:

console.log('b starting');
exports.done = false;
const a = require('./a.js');
console.log('in b, a.done = %j', a.done);
exports.done = true;
console.log('b done'); copy

main.js:

console.log('main starting');
const a = require('./a.js');
const b = require('./b.js');
console.log('in main, a.done = %j, b.done = %j', a.done, b.done); copy

当 main.js 加载 a.js 时，a.js 接着加载 b.js。 此时，b.js 尝试加载 a.js。 为了防止无限循环，将 a.js 导出对象的**未完成副本**返回给 b.js 模块。 然后 b.js 完成加载，并将其 exports 对象提供给 a.js 模块。

到 main.js 加载了两个模块时，它们都已完成。 因此，该程序的输出将是：

$ node main.js
main starting
a starting
b starting
in b, a.done = false
b done
in a, b.done = true
a done
in main, a.done = true, b.done = true copy

需要仔细规划以允许循环模块依赖项在应用程序中正常工作。

文件模块#

如果找不到确切的文件名，则 Node.js 将尝试加载带有添加的扩展名的所需文件名：.js、.json，最后是 .node。 加载具有不同扩展名（例如 .cjs）的文件时，必须将完整名称（包括文件扩展名）传递给 require()（例如 require('./file.cjs')）。

.json 文件被解析为 JSON 文本文件，.node 文件被解释为使用 process.dlopen() 加载的已编译的附加模块。 请参阅确定模块系统部分，以了解将使用哪种解析目标。

以 '/' 为前缀的必需模块是文件的绝对路径。 例如，require('/home/marco/foo.js') 将加载 /home/marco/foo.js 文件。

以 './' 为前缀的必需模块相对于调用 require() 的文件。 也就是说，circle.js 必须与 foo.js 位于同一目录中，才能使 require('./circle') 找到它。

如果没有前导 '/'、'./' 或 '../' 来指示文件，则该模块必须是核心模块，或者从 node_modules 文件夹加载。

如果给定的路径不存在，require() 将抛出 MODULE_NOT_FOUND 错误。

文件夹作为模块#

有三种方法可以将文件夹作为参数传递给 require()。

第一种方法是在文件夹的根目录中创建一个package.json 文件，该文件指定一个 main 模块。 package.json 文件的示例如下所示：

{ "name" : "some-library",
  "main" : "./lib/some-library.js" } copy

如果它位于 ./some-library 的文件夹中，则 require('./some-library') 将尝试加载 ./some-library/lib/some-library.js。

如果目录中不存在 package.json 文件，或者 "main" 条目缺失或无法解析，则 Node.js 将尝试从该目录中加载 index.js 或 index.node 文件。 例如，如果在上一个示例中没有 package.json 文件，则 require('./some-library') 将尝试加载：

• ./some-library/index.js
• ./some-library/index.node

如果这些尝试失败，则 Node.js 将使用默认错误报告整个模块丢失：

Error: Cannot find module 'some-library' copy

在以上所有三种情况下，调用 import('./some-library') 都会导致 ERR_UNSUPPORTED_DIR_IMPORT 错误。使用包的 子路径导出 或 子路径导入 可以提供与文件夹作为模块相同的包含组织优势，并且适用于 require 和 import。

从 node_modules 文件夹加载#

如果传递给 require() 的模块标识符不是内置模块，并且不以 '/'、'../' 或 './' 开头，则 Node.js 从当前模块的目录开始，并添加 /node_modules，然后尝试从该位置加载模块。Node.js 不会将 node_modules 附加到已经以 node_modules 结尾的路径。

如果在那里找不到，则移动到父目录，依此类推，直到到达文件系统的根目录。

例如，如果位于 '/home/ry/projects/foo.js' 的文件调用了 require('bar.js')，那么 Node.js 将按照以下顺序查找以下位置

• /home/ry/projects/node_modules/bar.js
• /home/ry/node_modules/bar.js
• /home/node_modules/bar.js
• /node_modules/bar.js

这允许程序本地化它们的依赖项，以避免冲突。

可以通过在模块名称后包含路径后缀来要求特定文件或与模块一起分发的子模块。例如，require('example-module/path/to/file') 将解析相对于 example-module 所在位置的 path/to/file。带后缀的路径遵循相同的模块解析语义。

从全局文件夹加载#

如果 NODE_PATH 环境变量设置为以冒号分隔的绝对路径列表，那么如果 Node.js 在其他地方找不到模块，它将在这些路径中搜索模块。

在 Windows 上，NODE_PATH 由分号 (;) 而不是冒号分隔。

NODE_PATH 最初是为了支持在当前 模块解析 算法定义之前从不同的路径加载模块而创建的。

NODE_PATH 仍然受支持，但现在 Node.js 生态系统已经确定了定位依赖模块的约定，因此不再那么必要。有时，依赖于 NODE_PATH 的部署会在人们不知道必须设置 NODE_PATH 时表现出令人惊讶的行为。有时，模块的依赖项会发生变化，导致加载不同的版本（甚至不同的模块），因为会搜索 NODE_PATH。

此外，Node.js 将在以下 GLOBAL_FOLDERS 列表中搜索

• 1: $HOME/.node_modules
• 2: $HOME/.node_libraries
• 3: $PREFIX/lib/node

其中 $HOME 是用户的主目录，$PREFIX 是 Node.js 配置的 node_prefix。

这些主要是出于历史原因。

强烈建议将依赖项放置在本地 node_modules 文件夹中。这些依赖项的加载速度更快，而且更可靠。

模块包装器#

在执行模块的代码之前，Node.js 会使用如下所示的函数包装器将其包装起来

(function(exports, require, module, __filename, __dirname) {
// Module code actually lives in here
}); copy

通过这样做，Node.js 实现了以下几个目标

• 它将顶层变量（用 var、const 或 let 定义的）的作用域限定在模块而不是全局对象中。
• 它有助于提供一些看起来是全局的变量，但实际上特定于模块，例如
  • module 和 exports 对象，实现者可以使用它们从模块导出值。
  • 便捷变量 __filename 和 __dirname，包含模块的绝对文件名和目录路径。

模块作用域#

console.log(__dirname);
// Prints: /Users/mjr
console.log(path.dirname(__filename));
// Prints: /Users/mjr copy

console.log(__filename);
// Prints: /Users/mjr/example.js
console.log(__dirname);
// Prints: /Users/mjr copy

// Importing a local module with a path relative to the `__dirname` or current
// working directory. (On Windows, this would resolve to .\path\myLocalModule.)
const myLocalModule = require('./path/myLocalModule');

// Importing a JSON file:
const jsonData = require('./path/filename.json');

// Importing a module from node_modules or Node.js built-in module:
const crypto = require('node:crypto'); copy

const assert = require('node:assert');
const realFs = require('node:fs');

const fakeFs = {};
require.cache.fs = { exports: fakeFs };

assert.strictEqual(require('fs'), fakeFs);
assert.strictEqual(require('node:fs'), realFs); copy

require.extensions['.sjs'] = require.extensions['.js']; copy

console.log(require.main); copy

node entry.js copy

Module {
  id: '.',
  path: '/absolute/path/to',
  exports: {},
  filename: '/absolute/path/to/entry.js',
  loaded: false,
  children: [],
  paths:
   [ '/absolute/path/to/node_modules',
     '/absolute/path/node_modules',
     '/absolute/node_modules',
     '/node_modules' ] } copy

module 对象#

• <Object>

在每个模块中，module 自由变量是对表示当前模块的对象的引用。 为了方便起见，module.exports 也可以通过 exports 模块全局变量访问。 module 实际上不是一个全局变量，而是每个模块的局部变量。

const EventEmitter = require('node:events');

module.exports = new EventEmitter();

// Do some work, and after some time emit
// the 'ready' event from the module itself.
setTimeout(() => {
  module.exports.emit('ready');
}, 1000); copy

const a = require('./a');
a.on('ready', () => {
  console.log('module "a" is ready');
}); copy

setTimeout(() => {
  module.exports = { a: 'hello' };
}, 0); copy

const x = require('./x');
console.log(x.a); copy

module.exports.hello = true; // Exported from require of module
exports = { hello: false };  // Not exported, only available in the module copy

module.exports = exports = function Constructor() {
  // ... etc.
}; copy

function require(/* ... */) {
  const module = { exports: {} };
  ((module, exports) => {
    // Module code here. In this example, define a function.
    function someFunc() {}
    exports = someFunc;
    // At this point, exports is no longer a shortcut to module.exports, and
    // this module will still export an empty default object.
    module.exports = someFunc;
    // At this point, the module will now export someFunc, instead of the
    // default object.
  })(module, module.exports);
  return module.exports;
} copy

Module 对象#

本节已移动到 模块: module 核心模块。

• module.builtinModules
• module.createRequire(filename)
• module.syncBuiltinESMExports()

Source map v3 支持#

本节已移动到 模块: module 核心模块。

• module.findSourceMap(path)
• 类: module.SourceMap
  • new SourceMap(payload)
  • sourceMap.payload
  • sourceMap.findEntry(lineNumber, columnNumber)