Node.js v18.7.0 文档

启用#

中英对照

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

访问主模块#

中英对照

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

包管理器的提示#

中英对照

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

.mjs 扩展名#

中英对照

由于 require() 的同步特性，无法使用它来加载 ECMAScript 模块文件。 尝试这样做会抛出 ERR_REQUIRE_ESM 错误。 改用 import()。

总结#

中英对照

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

缓存#

中英对照

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

模块缓存的注意事项#

中英对照

模块根据其解析的文件名进行缓存。 由于模块可能会根据调用模块的位置（从 node_modules 文件夹加载）解析为不同的文件名，因此如果 require('foo') 解析为不同的文件，则不能保证 require('foo') 将始终返回完全相同的对象。

核心模块#

中英对照

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

循环#

中英对照

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

文件模块#

中英对照

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

目录作为模块#

中英对照

可以通过三种方式将文件夹作为参数传给 require()。

从 node_modules 目录加载#

中英对照

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

从全局目录加载#

中英对照

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

模块封装器#

中英对照

在执行模块代码之前，Node.js 将使用如下所示的函数封装器对其进行封装：

模块作用域#

__dirname#

中英对照

当前模块的目录名。 这与 __filename 的 path.dirname() 相同。

__filename#

中英对照

当前模块的文件名。 这是当前模块文件的已解析符号链接的绝对路径。

exports#

中英对照

对 module.exports 的引用，其输入更短。 有关何时使用 exports 和何时使用 module.exports 的详细信息，请参阅有关导出的快捷方式的章节。

module#

中英对照

对当前模块的引用，请参阅有关 module 对象的部分。 特别是，module.exports 用于定义模块通过 require() 导出和提供的内容。

require(id)#

中英对照

用于导入模块、JSON 和本地文件。 模块可以从 node_modules 导入。 可以使用相对路径（例如 ./、./foo、./bar/baz、../foo）导入本地模块和 JSON 文件，该路径将根据 __dirname（如果有定义）命名的目录或当前工作目录进行解析。 POSIX 风格的相对路径以独立于操作系统的方式解析，这意味着上面的示例将在 Windows 上以与在 Unix 系统上相同的方式工作。

require.cache#

中英对照

模块在需要时缓存在此对象中。 通过从此对象中删除键值，下一次 require 将重新加载模块。 这不适用于原生插件，因为重新加载会导致错误。

require.extensions#

中英对照

指导 require 如何处理某些文件扩展名。

require.main#

中英对照

Module 对象代表 Node.js 进程启动时加载的入口脚本，如果程序的入口点不是 CommonJS 模块，则为 undefined。 请参阅“访问主模块”。

require.resolve(request[, options])#

中英对照

使用内部的 require() 工具查找模块的位置，但不加载模块，只返回解析的文件名。

require.resolve.paths(request)#

中英对照

如果 request 字符串引用核心模块，例如 http 或 fs，则返回包含在解析 request 或 null 期间搜索的路径的数组。

module 对象#

中英对照

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

module.children#

中英对照

这个模块首次需要的对象。

module.exports#

中英对照

module.exports 对象由 Module 系统创建。 有时这是不可接受的；许多人希望他们的模块成为某个类的实例。 为此，则将所需的导出对象赋值给 module.exports。 将所需的对象赋值给 exports 只会重新绑定本地的 exports 变量，这可能不是想要的。

导出的快捷方式#

中英对照

exports 变量在模块的文件级作用域内可用，并在评估模块之前被分配 module.exports 的值。

module.filename#

中英对照

模块的完全解析文件名。

module.id#

中英对照

模块的标识符。 通常这是完全解析的文件名。

module.isPreloading#

中英对照

module.loaded#

中英对照

模块是否已完成加载，或正在加载。

module.parent#

中英对照

首先需要这个模块的模块，如果当前模块是当前进程的入口点，则为 null，如果模块是由不是 CommonJS 模块的东西（例如：REPL 或 import）加载的，则为 undefined。

module.path#

中英对照

模块的目录名称。 这通常与 module.id 的 path.dirname() 相同。

module.paths#

中英对照

模块的搜索路径。

module.require(id)#

中英对照

module.require() 方法提供了一种加载模块的方法，就像从原始模块调用 require() 一样。

Module 对象#

中英对照

本章节移至模块：module 核心模块。

Source Map V3 的支持#

中英对照

本章节移至模块：module 核心模块。