Node.js v18.18.0 文档

Module 对象#

• <Object>

在与 Module 的实例交互时提供通用实用方法，module 变量经常出现在 CommonJS 模块中。 通过 import 'node:module' 或 require('node:module') 访问。

英Provides general utility methods when interacting with instances of Module, the module variable often seen in CommonJS modules. Accessed via import 'node:module' or require('node:module').

module.builtinModules#

• <string[]>

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

英A list of the names of all modules provided by Node.js. Can be used to verify if a module is maintained by a third party or not.

此上下文中的 module 与 模块封装器 提供的对象不同。 要访问它，需要 Module 模块：

英module in this context isn't the same object that's provided by the module wrapper. To access it, require the 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;拷贝

module.createRequire(filename)#

• filename <string> | <URL> 用于构造 require 函数的文件名。 必须是文件网址对象、文件网址字符串、或绝对路径字符串。
• 返回： <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'); 拷贝

module.isBuiltin(moduleName)#

• moduleName <string> 模块名称
• 返回： <boolean> 如果模块是内置的，则返回 true，否则返回 false

import { isBuiltin } from 'node:module';
isBuiltin('node:fs'); // true
isBuiltin('fs'); // true
isBuiltin('wss'); // false 拷贝

module.syncBuiltinESMExports()#

module.syncBuiltinESMExports() 方法更新内置 ES 模块 的所有实时绑定以匹配 CommonJS 导出的属性。 它不会在 ES 模块 中添加或删除导出的名称。

英The module.syncBuiltinESMExports() method updates all the live bindings for builtin ES Modules to match the properties of the CommonJS exports. It does not add or remove exported names from the 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);
}); 拷贝

源映射 v3 支持#

与源映射缓存交互的助手。 当启用源映射解析并且在模块的页脚中找到 源映射包含指令 时，将填充此缓存。

英Helpers for interacting with the source map cache. This cache is populated when source map parsing is enabled and source map include directives are found in a modules' footer.

要启用源映射解析，则 Node.js 必须使用标志 --enable-source-maps 运行、或者通过设置 NODE_V8_COVERAGE=dir 启用代码覆盖率。

英To enable source map parsing, Node.js must be run with the flag --enable-source-maps, or with code coverage enabled by setting NODE_V8_COVERAGE=dir.

// module.mjs
// In an ECMAScript module
import { findSourceMap, SourceMap } from 'node:module';// module.cjs
// In a CommonJS module
const { findSourceMap, SourceMap } = require('node:module');拷贝

module.findSourceMap(path)#

• path <string>
• 返回： <module.SourceMap> | <undefined> 如果找到源映射，则返回 module.SourceMap，否则返回 undefined。

path 是文件的解析路径，应为其获取相应的源映射。

英path is the resolved path for the file for which a corresponding source map should be fetched.

类：module.SourceMap#

new SourceMap(payload)#

• payload <Object>

创建新的 sourceMap 实例。

英Creates a new sourceMap instance.

payload 是一个对象，其键与 源映射 v3 格式 匹配：

英payload is an object with keys matching the Source map v3 format:

• file: <string>
• version: <number>
• sources: <string[]>
• sourcesContent: <string[]>
• names: <string[]>
• mappings: <string>
• sourceRoot: <string>

sourceMap.payload#

• 返回： <Object>

用于构造 SourceMap 实例的有效负载的获取器。

英Getter for the payload used to construct the SourceMap instance.

sourceMap.findEntry(lineOffset, columnOffset)#

• lineOffset <number> 生成的源中的零索引行号偏移量
• columnOffset <number> 生成的源中的零索引列号偏移量
• 返回： <Object>

给定生成的源文件中的行偏移量和列偏移量，如果找到，则返回表示原始文件中的 SourceMap 范围的对象，如果没有，则返回空对象。

英Given a line offset and column offset in the generated source file, returns an object representing the SourceMap range in the original file if found, or an empty object if not.

返回的对象包含以下键：

英The object returned contains the following keys:

• generatedLine: <number> 生成的源中范围开始的行偏移量
• generatedColumn: <number> 生成的源中范围开始的列偏移量
• originalSource: <string> 原始源的文件名，如 SourceMap 中报告的那样
• originalLine: <number> 原始源中范围开始的行偏移量
• originalColumn: <number> 原始源中范围开始的列偏移量
• name: <string>

返回的值表示 SourceMap 中显示的原始范围，基于零索引偏移量，而不是错误消息和 CallSite 对象中显示的 1 索引行号和列号。

英The returned value represents the raw range as it appears in the SourceMap, based on zero-indexed offsets, not 1-indexed line and column numbers as they appear in Error messages and CallSite objects.

要从错误堆栈和 CallSite 对象报告的行号和列号中获取相应的 1 索引行号和列号，请使用 sourceMap.findOrigin(lineNumber, columnNumber)

英To get the corresponding 1-indexed line and column numbers from a lineNumber and columnNumber as they are reported by Error stacks and CallSite objects, use sourceMap.findOrigin(lineNumber, columnNumber)

sourceMap.findOrigin(lineNumber, columnNumber)#

• lineNumber <number> 生成的源中调用站点的 1 索引行号
• columnOffset <number> 生成源中调用站点的 1 索引列号
• 返回： <Object>

给定生成源中调用站点的 1 索引行号和列号，在原始源中查找相应的调用站点位置。

英Given a 1-indexed lineNumber and columnNumber from a call site in the generated source, find the corresponding call site location in the original source.

如果在任何源映射中都找不到提供的行号和列号，则返回空对象。 否则，返回的对象包含以下键：

英If the lineNumber and columnNumber provided are not found in any source map, then an empty object is returned. Otherwise, the returned object contains the following keys:

• name: <string> | <undefined> 源映射中范围的名称（如果提供）
• fileName: <string> 原始源的文件名，如 SourceMap 中报告的那样
• lineNumber: <number> 原始源中相应调用站点的 1 索引 lineNumber
• columnNumber: <number> 原始源中相应调用站点的 1 索引列编号