Node.js v22.11.0 文档

util.callbackify(original)#

• original <Function> async 函数

  ¥original <Function> An async function

• 返回：<Function> 回调风格的函数

  ¥Returns: <Function> a callback style function

采用 async 函数（或返回 Promise 的函数）并返回遵循错误优先回调风格的函数，即将 (err, value) => ... 回调作为最后一个参数。在回调中，第一个参数将是拒绝原因（如果 Promise 已解决，则为 null），第二个参数将是已解决的值。

¥Takes an async function (or a function that returns a Promise) and returns a function following the error-first callback style, i.e. taking an (err, value) => ... callback as the last argument. In the callback, the first argument will be the rejection reason (or null if the Promise resolved), and the second argument will be the resolved value.

const util = require('node:util');

async function fn() {
  return 'hello world';
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
}); 拷贝

将打印：

¥Will print:

hello world 拷贝

回调是异步执行的，并且将具有有限的堆栈跟踪。如果回调抛出，进程将触发 'uncaughtException' 事件，如果不处理将退出。

¥The callback is executed asynchronously, and will have a limited stack trace. If the callback throws, the process will emit an 'uncaughtException' event, and if not handled will exit.

由于 null 作为回调的第一个参数有特殊含义，如果封装的函数使用假值为理由来拒绝 Promise，则该值被封装在 Error 中，原始值存储在名为 reason 的字段中。

¥Since null has a special meaning as the first argument to a callback, if a wrapped function rejects a Promise with a falsy value as a reason, the value is wrapped in an Error with the original value stored in a field named reason.

function fn() {
  return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  // When the Promise was rejected with `null` it is wrapped with an Error and
  // the original value is stored in `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null;  // true
}); 拷贝

util.debuglog(section[, callback])#

• section <string> 标识正在为其创建 debuglog 函数的应用部分的字符串。

  ¥section <string> A string identifying the portion of the application for which the debuglog function is being created.

• callback <Function> 第一次调用日志函数时调用的回调函数参数是更优化的日志函数。

  ¥callback <Function> A callback invoked the first time the logging function is called with a function argument that is a more optimized logging function.

• 返回：<Function> 日志函数

  ¥Returns: <Function> The logging function

util.debuglog() 方法用于创建函数，该函数根据 NODE_DEBUG 环境变量的存在有条件地将调试消息写入 stderr。如果 section 名称出现在该环境变量的值中，则返回的函数的操作类似于 console.error()。如果不是，则返回的函数是空操作。

¥The util.debuglog() method is used to create a function that conditionally writes debug messages to stderr based on the existence of the NODE_DEBUG environment variable. If the section name appears within the value of that environment variable, then the returned function operates similar to console.error(). If not, then the returned function is a no-op.

const util = require('node:util');
const debuglog = util.debuglog('foo');

debuglog('hello from foo [%d]', 123); 拷贝

如果这个程序在环境中与 NODE_DEBUG=foo 一起运行，则它会输出如下内容：

¥If this program is run with NODE_DEBUG=foo in the environment, then it will output something like:

FOO 3245: hello from foo [123] 拷贝

其中 3245 是进程 ID。如果它没有使用该环境变量集运行，则它不会打印任何内容。

¥where 3245 is the process id. If it is not run with that environment variable set, then it will not print anything.

section 还支持通配符：

¥The section supports wildcard also:

const util = require('node:util');
const debuglog = util.debuglog('foo-bar');

debuglog('hi there, it\'s foo-bar [%d]', 2333); 拷贝

如果它在环境中与 NODE_DEBUG=foo* 一起运行，则它将输出如下内容：

¥if it is run with NODE_DEBUG=foo* in the environment, then it will output something like:

FOO-BAR 3257: hi there, it's foo-bar [2333] 拷贝

可以在 NODE_DEBUG 环境变量中指定多个以逗号分隔的 section 名称：NODE_DEBUG=fs,net,tls。

¥Multiple comma-separated section names may be specified in the NODE_DEBUG environment variable: NODE_DEBUG=fs,net,tls.

可选的 callback 参数可用于用一个不同的函数替换日志函数，该函数没有任何初始化或不必要的封装。

¥The optional callback argument can be used to replace the logging function with a different function that doesn't have any initialization or unnecessary wrapping.

const util = require('node:util');
let debuglog = util.debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  debuglog = debug;
}); 拷贝

debuglog().enabled#

• <boolean>

util.debuglog().enabled 获取器用于基于 NODE_DEBUG 环境变量的存在创建可用于条件的测试。如果 section 名称出现在该环境变量的值中，则返回值将为 true。如果不是，则返回值将是 false。

¥The util.debuglog().enabled getter is used to create a test that can be used in conditionals based on the existence of the NODE_DEBUG environment variable. If the section name appears within the value of that environment variable, then the returned value will be true. If not, then the returned value will be false.

const util = require('node:util');
const enabled = util.debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
} 拷贝

如果这个程序在环境中与 NODE_DEBUG=foo 一起运行，则它会输出如下内容：

¥If this program is run with NODE_DEBUG=foo in the environment, then it will output something like:

hello from foo [123] 拷贝

util.debug(section)#

util.debuglog 的别名。当仅使用 util.debuglog().enabled 时，使用允许可读性并不意味着日志记录。

¥Alias for util.debuglog. Usage allows for readability of that doesn't imply logging when only using util.debuglog().enabled.

util.deprecate(fn, msg[, code])#

• fn <Function> 被弃用的函数。

  ¥fn <Function> The function that is being deprecated.

• msg <string> 调用弃用的函数时显示的警告消息。

  ¥msg <string> A warning message to display when the deprecated function is invoked.

• code <string> 弃用代码。有关代码列表，请参见 弃用的 API 列表。

  ¥code <string> A deprecation code. See the list of deprecated APIs for a list of codes.

• 返回：<Function> 弃用的函数被封装以触发警告。

  ¥Returns: <Function> The deprecated function wrapped to emit a warning.

util.deprecate() 方法以标记为已弃用的方式封装 fn（可能是函数或类）。

¥The util.deprecate() method wraps fn (which may be a function or class) in such a way that it is marked as deprecated.

const util = require('node:util');

exports.obsoleteFunction = util.deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.'); 拷贝

当调用时，util.deprecate() 将返回将使用 'warning' 事件触发 DeprecationWarning 的函数。第一次调用返回的函数时，警告将触发并打印到 stderr。触发警告后，将调用封装的函数而不触发警告。

¥When called, util.deprecate() will return a function that will emit a DeprecationWarning using the 'warning' event. The warning will be emitted and printed to stderr the first time the returned function is called. After the warning is emitted, the wrapped function is called without emitting a warning.

如果在多次调用 util.deprecate() 时提供了相同的可选 code，则该 code 只会触发一次警告。

¥If the same optional code is supplied in multiple calls to util.deprecate(), the warning will be emitted only once for that code.

const util = require('node:util');

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code 拷贝

如果使用 --no-deprecation 或 --no-warnings 命令行标志，或者如果在第一次弃用警告之前将 process.noDeprecation 属性设置为 true，则 util.deprecate() 方法不执行任何操作。

¥If either the --no-deprecation or --no-warnings command-line flags are used, or if the process.noDeprecation property is set to true prior to the first deprecation warning, the util.deprecate() method does nothing.

如果设置了 --trace-deprecation 或 --trace-warnings 命令行标志、或者 process.traceDeprecation 属性设置为 true，则在第一次调用已弃用的函数时会向 stderr 打印警告和堆栈跟踪。

¥If the --trace-deprecation or --trace-warnings command-line flags are set, or the process.traceDeprecation property is set to true, a warning and a stack trace are printed to stderr the first time the deprecated function is called.

如果设置了 --throw-deprecation 命令行标志、或者 process.throwDeprecation 属性设置为 true，则在调用已弃用的函数时将抛出异常。

¥If the --throw-deprecation command-line flag is set, or the process.throwDeprecation property is set to true, then an exception will be thrown when the deprecated function is called.

--throw-deprecation 命令行标志和 process.throwDeprecation 属性优先于 --trace-deprecation 和 process.traceDeprecation。

¥The --throw-deprecation command-line flag and process.throwDeprecation property take precedence over --trace-deprecation and process.traceDeprecation.

util.format(format[, ...args])#

• format <string> 类似 printf 的格式字符串。

  ¥format <string> A printf-like format string.

util.format() 方法使用第一个参数作为类似 printf 的格式字符串（其可以包含零个或多个格式说明符）来返回格式化的字符串。每个说明符都替换为来自相应参数的转换后的值。支持的说明符有：

¥The util.format() method returns a formatted string using the first argument as a printf-like format string which can contain zero or more format specifiers. Each specifier is replaced with the converted value from the corresponding argument. Supported specifiers are:

• %s：String 将用于转换除 BigInt、Object 和 -0 之外的所有值。BigInt 值将用 n 表示，没有用户定义的 toString 函数的对象使用具有选项 { depth: 0, colors: false, compact: 3 } 的 util.inspect() 进行检查。

  ¥%s: String will be used to convert all values except BigInt, Object and -0. BigInt values will be represented with an n and Objects that have no user defined toString function are inspected using util.inspect() with options { depth: 0, colors: false, compact: 3 }.

• %d：Number 将用于转换除 BigInt 和 Symbol 之外的所有值。

  ¥%d: Number will be used to convert all values except BigInt and Symbol.

• %i：parseInt(value, 10) 用于除 BigInt 和 Symbol 之外的所有值。

  ¥%i: parseInt(value, 10) is used for all values except BigInt and Symbol.

• %f：parseFloat(value) 用于除 Symbol 之外的所有值。

  ¥%f: parseFloat(value) is used for all values expect Symbol.

• %j：JSON.如果参数包含循环引用，则替换为字符串 '[Circular]'。

  ¥%j: JSON. Replaced with the string '[Circular]' if the argument contains circular references.

• %o：Object。具有通用 JavaScript 对象格式的对象的字符串表示形式。类似于具有选项 { showHidden: true, showProxy: true } 的 util.inspect()。这将显示完整的对象，包括不可枚举的属性和代理。

  ¥%o: Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() with options { showHidden: true, showProxy: true }. This will show the full object including non-enumerable properties and proxies.

• %O：Object。具有通用 JavaScript 对象格式的对象的字符串表示形式。类似于没有选项的 util.inspect()。这将显示完整的对象，但不包括不可枚举的属性和代理。

  ¥%O: Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() without options. This will show the full object not including non-enumerable properties and proxies.

• %c：CSS。此说明符被忽略，将跳过任何传入的 CSS。

  ¥%c: CSS. This specifier is ignored and will skip any CSS passed in.

• %%：单个百分号 ('%')。这不消费参数。

  ¥%%: single percent sign ('%'). This does not consume an argument.

• 返回：<string> 格式化的字符串

  ¥Returns: <string> The formatted string

如果说明符没有相应的参数，则不会替换它：

¥If a specifier does not have a corresponding argument, it is not replaced:

util.format('%s:%s', 'foo');
// Returns: 'foo:%s' 拷贝

如果其类型不是 string，则不属于格式字符串的值将使用 util.inspect() 进行格式化。

¥Values that are not part of the format string are formatted using util.inspect() if their type is not string.

如果传给 util.format() 方法的参数多于说明符的数量，则额外的参数将以空格分隔串联到返回的字符串：

¥If there are more arguments passed to the util.format() method than the number of specifiers, the extra arguments are concatenated to the returned string, separated by spaces:

util.format('%s:%s', 'foo', 'bar', 'baz');
// Returns: 'foo:bar baz' 拷贝

如果第一个参数不包含有效的格式说明符，则 util.format() 返回以空格分隔的所有参数的串联的字符串：

¥If the first argument does not contain a valid format specifier, util.format() returns a string that is the concatenation of all arguments separated by spaces:

util.format(1, 2, 3);
// Returns: '1 2 3' 拷贝

如果只有一个参数传给 util.format()，则它会按原样返回，不进行任何格式化：

¥If only one argument is passed to util.format(), it is returned as it is without any formatting:

util.format('%% %s');
// Returns: '%% %s' 拷贝

util.format() 是同步的方法，旨在用作调试工具。某些输入值可能会产生显着的性能开销，从而阻塞事件循环。小心使用此函数，切勿在热代码路径中使用。

¥util.format() is a synchronous method that is intended as a debugging tool. Some input values can have a significant performance overhead that can block the event loop. Use this function with care and never in a hot code path.

util.formatWithOptions(inspectOptions, format[, ...args])#

• inspectOptions <Object>

• format <string>

此函数与 util.format() 相同，不同之处在于它接受 inspectOptions 参数，该参数指定传给 util.inspect() 的选项。

¥This function is identical to util.format(), except in that it takes an inspectOptions argument which specifies options that are passed along to util.inspect().

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// Returns 'See object { foo: 42 }', where `42` is colored as a number
// when printed to a terminal. 拷贝

util.getCallSite(frames)#

• frames <number> 堆栈跟踪中返回的帧数。默认值：10。允许的范围在 1 到 200 之间。

  ¥frames <number> Number of frames returned in the stacktrace. Default: 10. Allowable range is between 1 and 200.

• 返回：<Object[]> 堆栈跟踪对象数组

  ¥Returns: <Object[]> An array of stacktrace objects

  • functionName <string> 返回与此堆栈框架关联的函数的名称。

    ¥functionName <string> Returns the name of the function associated with this stack frame.

  • scriptName <string> 返回包含此 StackFrame 函数脚本的资源的名称。

    ¥scriptName <string> Returns the name of the resource that contains the script for the function for this StackFrame.

  • lineNumber <number> 返回关联函数调用行的编号（以 1 为基数）。

    ¥lineNumber <number> Returns the number, 1-based, of the line for the associate function call.

  • column <number> 返回关联函数调用行上以 1 为基数的列偏移量。

    ¥column <number> Returns the 1-based column offset on the line for the associated function call.

返回包含调用者函数堆栈的堆栈跟踪对象数组。

¥Returns an array of stacktrace objects containing the stack of the caller function.

const util = require('node:util');

function exampleFunction() {
  const callSites = util.getCallSite();

  console.log('Call Sites:');
  callSites.forEach((callSite, index) => {
    console.log(`CallSite ${index + 1}:`);
    console.log(`Function Name: ${callSite.functionName}`);
    console.log(`Script Name: ${callSite.scriptName}`);
    console.log(`Line Number: ${callSite.lineNumber}`);
    console.log(`Column Number: ${callSite.column}`);
  });
  // CallSite 1:
  // Function Name: exampleFunction
  // Script Name: /home/example.js
  // Line Number: 5
  // Column Number: 26

  // CallSite 2:
  // Function Name: anotherFunction
  // Script Name: /home/example.js
  // Line Number: 22
  // Column Number: 3

  // ...
}

// A function to simulate another stack layer
function anotherFunction() {
  exampleFunction();
}

anotherFunction(); 拷贝

util.getSystemErrorName(err)#

• err <number>

• 返回：<string>

  ¥Returns: <string>

返回来自 Node.js API 的数字错误码的字符串名称。错误码和错误名称之间的映射是平台相关的。常见错误名称见 常见系统错误。

¥Returns the string name for a numeric error code that comes from a Node.js API. The mapping between error codes and error names is platform-dependent. See Common System Errors for the names of common errors.

fs.access('file/that/does/not/exist', (err) => {
  const name = util.getSystemErrorName(err.errno);
  console.error(name);  // ENOENT
}); 拷贝

util.getSystemErrorMap()#

• 返回：<Map>

  ¥Returns: <Map>

返回来自 Node.js API 的可用的所有系统错误码的映射。错误码和错误名称之间的映射是平台相关的。常见错误名称见 常见系统错误。

¥Returns a Map of all system error codes available from the Node.js API. The mapping between error codes and error names is platform-dependent. See Common System Errors for the names of common errors.

fs.access('file/that/does/not/exist', (err) => {
  const errorMap = util.getSystemErrorMap();
  const name = errorMap.get(err.errno);
  console.error(name);  // ENOENT
}); 拷贝

util.inherits(constructor, superConstructor)#

• constructor <Function>

• superConstructor <Function>

不鼓励使用 util.inherits()。请使用 ES6 class 和 extends 关键字来获得语言级别的继承支持。另请注意，这两种款式都是 语义上不兼容。

¥Usage of util.inherits() is discouraged. Please use the ES6 class and extends keywords to get language level inheritance support. Also note that the two styles are semantically incompatible.

将原型方法从一个 构造函数 继承到另一个。constructor 的原型将被设置为从 superConstructor 创建的新对象。

¥Inherit the prototype methods from one constructor into another. The prototype of constructor will be set to a new object created from superConstructor.

这主要是在 Object.setPrototypeOf(constructor.prototype, superConstructor.prototype) 之上添加了一些输入验证。作为额外的便利，superConstructor 将可通过 constructor.super_ 属性访问。

¥This mainly adds some input validation on top of Object.setPrototypeOf(constructor.prototype, superConstructor.prototype). As an additional convenience, superConstructor will be accessible through the constructor.super_ property.

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

function MyStream() {
  EventEmitter.call(this);
}

util.inherits(MyStream, EventEmitter);

MyStream.prototype.write = function(data) {
  this.emit('data', data);
};

const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('It works!'); // Received data: "It works!" 拷贝

使用 class 和 extends 的 ES6 示例：

¥ES6 example using class and extends:

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

class MyStream extends EventEmitter {
  write(data) {
    this.emit('data', data);
  }
}

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6'); 拷贝

util.inspect(object[, options])#

util.inspect(object[, showHidden[, depth[, colors]]])#

• object <any> 任何 JavaScript 原始类型或 Object。

  ¥object <any> Any JavaScript primitive or Object.

• options <Object>

  • showHidden <boolean> 如果为 true，则 object 的不可枚举符号和属性包含在格式化的结果中。WeakMap 和 WeakSet 条目以及用户定义的原型属性（不包括方法属性）也包括在内。默认值：false。

    ¥showHidden <boolean> If true, object's non-enumerable symbols and properties are included in the formatted result. WeakMap and WeakSet entries are also included as well as user defined prototype properties (excluding method properties). Default: false.

  • depth <number> 指定格式化 object 时递归的次数。这对于检查大型对象很有用。要递归到最大调用堆栈大小，则传入 Infinity 或 null。默认值：2。

    ¥depth <number> Specifies the number of times to recurse while formatting object. This is useful for inspecting large objects. To recurse up to the maximum call stack size pass Infinity or null. Default: 2.

  • colors <boolean> 如果为 true，则输出的样式为 ANSI 颜色代码。颜色是可自定义的。参见 自定义 util.inspect 颜色。默认值：false。

    ¥colors <boolean> If true, the output is styled with ANSI color codes. Colors are customizable. See Customizing util.inspect colors. Default: false.

  • customInspect <boolean> 如果为 false，则 [util.inspect.custom](depth, opts, inspect) 函数不被调用。默认值：true。

    ¥customInspect <boolean> If false, [util.inspect.custom](depth, opts, inspect) functions are not invoked. Default: true.

  • showProxy <boolean> 如果 true，Proxy 检查包括 target 和 handler 对象。默认值：false。

    ¥showProxy <boolean> If true, Proxy inspection includes the target and handler objects. Default: false.

  • maxArrayLength <integer> 指定格式化时要包括的 Array、TypedArray、Map、Set、WeakMap 和 WeakSet 元素的最大数量。设置为 null 或 Infinity 则显示所有元素。设置为 0 或负数则不显示任何元素。默认值：100。

    ¥maxArrayLength <integer> Specifies the maximum number of Array, TypedArray, Map, Set, WeakMap, and WeakSet elements to include when formatting. Set to null or Infinity to show all elements. Set to 0 or negative to show no elements. Default: 100.

  • maxStringLength <integer> 指定格式化时要包含的最大字符数。设置为 null 或 Infinity 则显示所有元素。设置为 0 或负数则不显示字符。默认值：10000。

    ¥maxStringLength <integer> Specifies the maximum number of characters to include when formatting. Set to null or Infinity to show all elements. Set to 0 or negative to show no characters. Default: 10000.

  • breakLength <integer> 输入值在多行中拆分的长度。设置为 Infinity 以将输入格式化为单行（结合 compact 设置为 true 或任何数字 >= 1）。默认值：80。

    ¥breakLength <integer> The length at which input values are split across multiple lines. Set to Infinity to format the input as a single line (in combination with compact set to true or any number >= 1). Default: 80.

  • compact <boolean> | <integer> 将此设置为 false 会导致每个对象的键显示在新行上。它将在比 breakLength 长的文本中换行。如果设置为数字，则只要所有属性都适合 breakLength，则最多 n 个内部元素将合并在一行中。短数组元素也组合在一起。有关更多信息，请参阅下面的示例。默认值：3。

    ¥compact <boolean> | <integer> Setting this to false causes each object key to be displayed on a new line. It will break on new lines in text that is longer than breakLength. If set to a number, the most n inner elements are united on a single line as long as all properties fit into breakLength. Short array elements are also grouped together. For more information, see the example below. Default: 3.

  • sorted <boolean> | <Function> 如果设置为 true 或函数，则对象的所有属性以及 Set 和 Map 条目都将在结果字符串中排序。如果设置为 true，则使用 默认排序。如果设置为函数，则用作 比较函数。

    ¥sorted <boolean> | <Function> If set to true or a function, all properties of an object, and Set and Map entries are sorted in the resulting string. If set to true the default sort is used. If set to a function, it is used as a compare function.

  • getters <boolean> | <string> 如果设置为 true，则检查获取器。如果设置为 'get'，则只检查没有相应设置器的获取器。如果设置为 'set'，则只检查具有相应设置器的获取器。这可能会导致副作用，具体取决于获取器函数。默认值：false。

    ¥getters <boolean> | <string> If set to true, getters are inspected. If set to 'get', only getters without a corresponding setter are inspected. If set to 'set', only getters with a corresponding setter are inspected. This might cause side effects depending on the getter function. Default: false.

  • numericSeparator <boolean> 如果设置为 true，则使用下划线分隔所有 bigint 和数字中的每三个数字。默认值：false。

    ¥numericSeparator <boolean> If set to true, an underscore is used to separate every three digits in all bigints and numbers. Default: false.

• 返回：<string> object 的表示。

  ¥Returns: <string> The representation of object.

util.inspect() 方法返回用于调试的 object 的字符串表示。util.inspect 的输出可能随时更改，不应以编程方式依赖。可以传入额外的 options 来改变结果。util.inspect() 将使用构造函数的名称和/或 @@toStringTag 为检查的值制作可识别的标签。

¥The util.inspect() method returns a string representation of object that is intended for debugging. The output of util.inspect may change at any time and should not be depended upon programmatically. Additional options may be passed that alter the result. util.inspect() will use the constructor's name and/or @@toStringTag to make an identifiable tag for an inspected value.

class Foo {
  get [Symbol.toStringTag]() {
    return 'bar';
  }
}

class Bar {}

const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });

util.inspect(new Foo()); // 'Foo [bar] {}'
util.inspect(new Bar()); // 'Bar {}'
util.inspect(baz);       // '[foo] {}' 拷贝

循环引用通过使用引用索引指向其锚点：

¥Circular references point to their anchor by using a reference index:

const { inspect } = require('node:util');

const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// } 拷贝

以下示例检查 util 对象的所有属性：

¥The following example inspects all properties of the util object:

const util = require('node:util');

console.log(util.inspect(util, { showHidden: true, depth: null })); 拷贝

以下示例高亮了 compact 选项的效果：

¥The following example highlights the effect of the compact option:

const util = require('node:util');

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
      'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
    'test',
    'foo']], 4],
  b: new Map([['za', 1], ['zb', 'test']]),
};
console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// Setting `compact` to false or an integer creates more reader friendly output.
console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet,\n' +
//           'consectetur adipiscing elit, sed do eiusmod \n' +
//           'tempor incididunt ut labore et dolore magna aliqua.',
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map(2) {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line. 拷贝

showHidden 选项允许检查 WeakMap 和 WeakSet 条目。如果条目多于 maxArrayLength，则无法保证显示哪些条目。这意味着两次检索相同的 WeakSet 条目可能会导致不同的输出。此外，没有剩余强引用的条目可能随时被垃圾回收。

¥The showHidden option allows WeakMap and WeakSet entries to be inspected. If there are more entries than maxArrayLength, there is no guarantee which entries are displayed. That means retrieving the same WeakSet entries twice may result in different output. Furthermore, entries with no remaining strong references may be garbage collected at any time.

const { inspect } = require('node:util');

const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } } 拷贝

sorted 选项确保对象的属性插入顺序不会影响 util.inspect() 的结果。

¥The sorted option ensures that an object's property insertion order does not impact the result of util.inspect().

const { inspect } = require('node:util');
const assert = require('node:assert');

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
};
assert.strict.equal(
  inspect(o1, { sorted: true }),
  inspect(o2, { sorted: true }),
); 拷贝

numericSeparator 选项为所有数字每三位添加一个下划线。

¥The numericSeparator option adds an underscore every three digits to all numbers.

const { inspect } = require('node:util');

const thousand = 1_000;
const million = 1_000_000;
const bigNumber = 123_456_789n;
const bigDecimal = 1_234.123_45;

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45 拷贝

util.inspect() 是用于调试的同步方法。其最大输出长度约为 128 MiB。造成更长输出的输入将被截断。

¥util.inspect() is a synchronous method intended for debugging. Its maximum output length is approximately 128 MiB. Inputs that result in longer output will be truncated.

自定义 util.inspect 颜色#

¥Customizing util.inspect colors

util.inspect 的颜色输出（如果启用）可通过 util.inspect.styles 和 util.inspect.colors 属性全局地自定义。

¥Color output (if enabled) of util.inspect is customizable globally via the util.inspect.styles and util.inspect.colors properties.

util.inspect.styles 是将样式名称与来自 util.inspect.colors 的颜色相关联的映射。

¥util.inspect.styles is a map associating a style name to a color from util.inspect.colors.

默认的样式和相关的颜色为：

¥The default styles and associated colors are:

• bigint：yellow

• boolean：yellow

• date：magenta

• module：underline

• name：（没有样式）

  ¥name: (no styling)

• null：bold

• number：yellow

• regexp：red

• special：cyan（例如，Proxies）

  ¥special: cyan (e.g., Proxies)

• string：green

• symbol：green

• undefined：grey

颜色样式使用 ANSI 控制代码，可能并非所有终端都支持。要验证颜色支持，则使用 tty.hasColors()。

¥Color styling uses ANSI control codes that may not be supported on all terminals. To verify color support use tty.hasColors().

下面列出了预定义的控制代码（分组为 "修饰符"、"前景色" 和 "背景颜色"）。

¥Predefined control codes are listed below (grouped as "Modifiers", "Foreground colors", and "Background colors").

修饰符#

¥Modifiers

修饰符的支持因不同的终端而异。如果不支持，则它们通常会被忽略。

¥Modifier support varies throughout different terminals. They will mostly be ignored, if not supported.

• reset - 将所有（颜色）修改器重置为其默认值

  ¥reset - Resets all (color) modifiers to their defaults

• bold - 将文本设为粗体

  ¥bold - Make text bold

• italic - 将文本设置为斜体

  ¥italic - Make text italic

• underline - 给字面加下划线

  ¥underline - Make text underlined

• strikethrough - 在文本中心放置一条水平线（别名：strikeThrough、crossedout、crossedOut）

  ¥strikethrough - Puts a horizontal line through the center of the text (Alias: strikeThrough, crossedout, crossedOut)

• hidden - 打印文本，但使其不可见（别名：隐藏）

  ¥hidden - Prints the text, but makes it invisible (Alias: conceal)

• dim - 颜色强度降低（别名：faint）

  ¥dim - Decreased color intensity (Alias: faint)

• overlined - 使字面上划线

  ¥overlined - Make text overlined

• blink - 以一定间隔隐藏和显示文本

  ¥blink - Hides and shows the text in an interval

• inverse - 交换前景色和背景色（别名：swapcolors、swapColors）

  ¥inverse - Swap foreground and background colors (Alias: swapcolors, swapColors)

• doubleunderline - 使文本加双下划线（别名：doubleUnderline）

  ¥doubleunderline - Make text double underlined (Alias: doubleUnderline)

• framed - 在文本周围画一个框

  ¥framed - Draw a frame around the text

前景色#

¥Foreground colors

• black

• red

• green

• yellow

• blue

• magenta

• cyan

• white

• gray（别名：grey、blackBright）

  ¥gray (alias: grey, blackBright)

• redBright

• greenBright

• yellowBright

• blueBright

• magentaBright

• cyanBright

• whiteBright

背景颜色#

¥Background colors

• bgBlack

• bgRed

• bgGreen

• bgYellow

• bgBlue

• bgMagenta

• bgCyan

• bgWhite

• bgGray（别名：bgGrey、bgBlackBright）

  ¥bgGray (alias: bgGrey, bgBlackBright)

• bgRedBright

• bgGreenBright

• bgYellowBright

• bgBlueBright

• bgMagentaBright

• bgCyanBright

• bgWhiteBright

对象的自定义检查函数#

¥Custom inspection functions on objects

对象也可以定义自己的 [util.inspect.custom](depth, opts, inspect) 函数，util.inspect() 将在检查对象时调用并使用其结果。

¥Objects may also define their own [util.inspect.custom](depth, opts, inspect) function, which util.inspect() will invoke and use the result of when inspecting the object.

const util = require('node:util');

class Box {
  constructor(value) {
    this.value = value;
  }

  [util.inspect.custom](depth, options, inspect) {
    if (depth < 0) {
      return options.stylize('[Box]', 'special');
    }

    const newOptions = Object.assign({}, options, {
      depth: options.depth === null ? null : options.depth - 1,
    });

    // Five space padding because that's the size of "Box< ".
    const padding = ' '.repeat(5);
    const inner = inspect(this.value, newOptions)
                  .replace(/\n/g, `\n${padding}`);
    return `${options.stylize('Box', 'special')}< ${inner} >`;
  }
}

const box = new Box(true);

util.inspect(box);
// Returns: "Box< true >" 拷贝

自定义的 [util.inspect.custom](depth, opts, inspect) 函数通常返回一个字符串，但也可能返回一个由 util.inspect() 相应格式化的任何类型的值。

¥Custom [util.inspect.custom](depth, opts, inspect) functions typically return a string but may return a value of any type that will be formatted accordingly by util.inspect().

const util = require('node:util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj[util.inspect.custom] = (depth) => {
  return { bar: 'baz' };
};

util.inspect(obj);
// Returns: "{ bar: 'baz' }" 拷贝

util.inspect.custom#

• <symbol> 可用于声明自定义检查函数。

  ¥<symbol> that can be used to declare custom inspect functions.

除了可以通过 util.inspect.custom 访问外，这个符号是 全局注册，在任何环境下都可以作为 Symbol.for('nodejs.util.inspect.custom') 访问。

¥In addition to being accessible through util.inspect.custom, this symbol is registered globally and can be accessed in any environment as Symbol.for('nodejs.util.inspect.custom').

使用此允许以可移植方式编写代码，以便在 Node.js 环境中使用自定义检查功能并在浏览器中忽略。util.inspect() 函数本身作为第三个参数传给自定义检查函数以允许进一步的可移植性。

¥Using this allows code to be written in a portable fashion, so that the custom inspect function is used in an Node.js environment and ignored in the browser. The util.inspect() function itself is passed as third argument to the custom inspect function to allow further portability.

const customInspectSymbol = Symbol.for('nodejs.util.inspect.custom');

class Password {
  constructor(value) {
    this.value = value;
  }

  toString() {
    return 'xxxxxxxx';
  }

  [customInspectSymbol](depth, inspectOptions, inspect) {
    return `Password <${this.toString()}>`;
  }
}

const password = new Password('r0sebud');
console.log(password);
// Prints Password <xxxxxxxx> 拷贝

有关详细信息，请参阅 对象的自定义检查函数。

¥See Custom inspection functions on Objects for more details.

util.inspect.defaultOptions#

defaultOptions 值允许自定义 util.inspect 使用的默认选项。这对于像 console.log 或 util.format 这样隐式调用 util.inspect 的函数很有用。它应设置为包含一个或多个有效 util.inspect() 选项的对象。也支持直接设置选项属性。

¥The defaultOptions value allows customization of the default options used by util.inspect. This is useful for functions like console.log or util.format which implicitly call into util.inspect. It shall be set to an object containing one or more valid util.inspect() options. Setting option properties directly is also supported.

const util = require('node:util');
const arr = Array(101).fill(0);

console.log(arr); // Logs the truncated array
util.inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array 拷贝

util.isDeepStrictEqual(val1, val2)#

• val1 <any>

• val2 <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果 val1 和 val2 之间存在深度严格相等，则返回 true。否则，返回 false。

¥Returns true if there is deep strict equality between val1 and val2. Otherwise, returns false.

有关深度严格相等的更多信息，请参见 assert.deepStrictEqual()。

¥See assert.deepStrictEqual() for more information about deep strict equality.

类：util.MIMEType#

¥Class: util.MIMEType

MIMEType 类 的实现。

¥An implementation of the MIMEType class.

按照浏览器的约定，MIMEType 对象的所有属性都被实现为类原型上的获取器和设置器，而不是对象本身的数据属性。

¥In accordance with browser conventions, all properties of MIMEType objects are implemented as getters and setters on the class prototype, rather than as data properties on the object itself.

MIME 字符串是包含多个有意义的组件的结构化字符串。解析后，将返回一个 MIMEType 对象，其中包含每个组件的属性。

¥A MIME string is a structured string containing multiple meaningful components. When parsed, a MIMEType object is returned containing properties for each of these components.

构造器：new MIMEType(input)#

¥Constructor: new MIMEType(input)

• input <string> 要解析的输入 MIME

  ¥input <string> The input MIME to parse

通过解析 input 创建一个新的 MIMEType 对象。

¥Creates a new MIMEType object by parsing the input.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/plain');const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/plain');拷贝

如果 input 不是有效的 MIME，将抛出 TypeError。注意，会将给定的值强制转换为字符串。例如：

¥A TypeError will be thrown if the input is not a valid MIME. Note that an effort will be made to coerce the given values into strings. For instance:

import { MIMEType } from 'node:util';
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plainconst { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plain拷贝

mime.type#

• <string>

获取和设置 MIME 的类型部分。

¥Gets and sets the type portion of the MIME.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascriptconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascript拷贝

mime.subtype#

• <string>

获取和设置 MIME 的子类型部分。

¥Gets and sets the subtype portion of the MIME.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascriptconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascript拷贝

mime.essence#

• <string>

获取 MIME 的精髓。这个属性是只读的。使用 mime.type 或 mime.subtype 改变 MIME。

¥Gets the essence of the MIME. This property is read only. Use mime.type or mime.subtype to alter the MIME.

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=valueconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=value拷贝

mime.params#

• <MIMEParams>

获取表示 MIME 参数的 MIMEParams 对象。这个属性是只读的。有关详细信息，请参阅 MIMEParams 文档。

¥Gets the MIMEParams object representing the parameters of the MIME. This property is read-only. See MIMEParams documentation for details.

mime.toString()#

• 返回：<string>

  ¥Returns: <string>

MIMEType 对象上的 toString() 方法返回序列化的 MIME。

¥The toString() method on the MIMEType object returns the serialized MIME.

因为符合标准的需要，该方法不允许用户自定义 MIME 的序列化过程。

¥Because of the need for standard compliance, this method does not allow users to customize the serialization process of the MIME.

mime.toJSON()#

• 返回：<string>

  ¥Returns: <string>

mime.toString() 的别名。

¥Alias for mime.toString().

当 MIMEType 对象用 JSON.stringify() 序列化时，会自动调用此方法。

¥This method is automatically called when an MIMEType object is serialized with JSON.stringify().

import { MIMEType } from 'node:util';

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]const { MIMEType } = require('node:util');

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]拷贝

类：util.MIMEParams#

¥Class: util.MIMEParams

MIMEParams API 提供对 MIMEType 参数的读写访问。

¥The MIMEParams API provides read and write access to the parameters of a MIMEType.

构造器：new MIMEParams()#

¥Constructor: new MIMEParams()

使用空参数创建一个新的 MIMEParams 对象

¥Creates a new MIMEParams object by with empty parameters

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();const { MIMEParams } = require('node:util');

const myParams = new MIMEParams();拷贝

mimeParams.delete(name)#

• name <string>

删除名称为 name 的所有名称-值对。

¥Remove all name-value pairs whose name is name.

mimeParams.entries()#

• 返回：<Iterator>

  ¥Returns: <Iterator>

返回参数中每个名称-值对的迭代器。迭代器的每一项都是 JavaScript Array。数组的第一项是 name，数组的第二项是 value。

¥Returns an iterator over each of the name-value pairs in the parameters. Each item of the iterator is a JavaScript Array. The first item of the array is the name, the second item of the array is the value.

mimeParams.get(name)#

• name <string>

• 返回：<string> | <null> 如果没有具有给定 name 的名称/值对，则为字符串或 null。

  ¥Returns: <string> | <null> A string or null if there is no name-value pair with the given name.

返回名称为 name 的第一个名称-值对的值。如果没有这样的对，则返回 null。

¥Returns the value of the first name-value pair whose name is name. If there are no such pairs, null is returned.

mimeParams.has(name)#

• name <string>

• 返回：<boolean>

  ¥Returns: <boolean>

如果至少有一个名称-值对的名称为 name，则返回 true。

¥Returns true if there is at least one name-value pair whose name is name.

mimeParams.keys()#

• 返回：<Iterator>

  ¥Returns: <Iterator>

返回每个名称-值对名称的迭代器。

¥Returns an iterator over the names of each name-value pair.

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   barconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   bar拷贝

mimeParams.set(name, value)#

• name <string>

• value <string>

将与 name 关联的 MIMEParams 对象中的值设置为 value。如果有任何名称为 name 的预先存在的名称-值对，将第一个这样的对的值设置为 value。

¥Sets the value in the MIMEParams object associated with name to value. If there are any pre-existing name-value pairs whose names are name, set the first such pair's value to value.

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// Prints: foo=def;bar=1;baz=xyzconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// Prints: foo=def;bar=1;baz=xyz拷贝

mimeParams.values()#

• 返回：<Iterator>

  ¥Returns: <Iterator>

返回每个名称-值对的值的迭代器。

¥Returns an iterator over the values of each name-value pair.

mimeParams[@@iterator]()#

• 返回：<Iterator>

  ¥Returns: <Iterator>

mimeParams.entries() 的别名。

¥Alias for mimeParams.entries().

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz bazconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz baz拷贝

util.parseArgs([config])#

• config <Object> 用于提供解析参数和配置解析器。config 支持以下属性：

  ¥config <Object> Used to provide arguments for parsing and to configure the parser. config supports the following properties:

  • args <string[]> 参数字符串数组。默认值：process.argv 删除了 execPath 和 filename。

    ¥args <string[]> array of argument strings. Default: process.argv with execPath and filename removed.

  • options <Object> 用于描述解析器已知的参数。options 的键是选项的长名称，值是 <Object>，接受以下属性：

    ¥options <Object> Used to describe arguments known to the parser. Keys of options are the long names of options and values are an <Object> accepting the following properties:

    • type <string> 参数类型，必须是 boolean 或 string。

      ¥type <string> Type of argument, which must be either boolean or string.

    • multiple <boolean> 是否可以多次提供该选项。如果为 true，则所有的值都会被收集到一个数组中。如果为 false，则选项的值是最后获胜的。默认值：false。

      ¥multiple <boolean> Whether this option can be provided multiple times. If true, all values will be collected in an array. If false, values for the option are last-wins. Default: false.

    • short <string> 选项的单个字符别名。

      ¥short <string> A single character alias for the option.

    • default <string> | <boolean> | <string[]> | <boolean[]> 未由 args 设置时的默认选项值。它必须与 type 属性的类型相同。当 multiple 为 true 时，它必须是一个数组。

      ¥default <string> | <boolean> | <string[]> | <boolean[]> The default option value when it is not set by args. It must be of the same type as the type property. When multiple is true, it must be an array.

  • strict <boolean> 当遇到未知参数时，或者当传入的参数与 options 中配置的 type 不匹配时，是否应该抛出错误。默认值：true。

    ¥strict <boolean> Should an error be thrown when unknown arguments are encountered, or when arguments are passed that do not match the type configured in options. Default: true.

  • allowPositionals <boolean> 此命令是否接受位置参数。默认值：如果 strict 是 true，则为 false，否则为 true。

    ¥allowPositionals <boolean> Whether this command accepts positional arguments. Default: false if strict is true, otherwise true.

  • allowNegative <boolean> 如果是 true，则允许通过在选项名称前加上 --no- 来明确将布尔选项设置为 false。默认值：false。

    ¥allowNegative <boolean> If true, allows explicitly setting boolean options to false by prefixing the option name with --no-. Default: false.

  • tokens <boolean> 返回解析的令牌。这对于扩展内置行为很有用，从添加额外检查到以不同方式重新处理令牌。默认值：false。

    ¥tokens <boolean> Return the parsed tokens. This is useful for extending the built-in behavior, from adding additional checks through to reprocessing the tokens in different ways. Default: false.

• 返回：<Object> 解析后的命令行参数：

  ¥Returns: <Object> The parsed command line arguments:

  • values <Object> 解析的选项名称与其 <string> 或 <boolean> 值的映射。

    ¥values <Object> A mapping of parsed option names with their <string> or <boolean> values.

  • positionals <string[]> 位置参数。

    ¥positionals <string[]> Positional arguments.

  • tokens <Object[]> | <undefined> 参见 parseArgs 标记 部分。仅当 config 包含 tokens: true 时才返回。

    ¥tokens <Object[]> | <undefined> See parseArgs tokens section. Only returned if config includes tokens: true.

为命令行参数解析提供比直接与 process.argv 交互更高级别的 API。采用预期参数的规范并返回带有解析选项和位置的结构化对象。

¥Provides a higher level API for command-line argument parsing than interacting with process.argv directly. Takes a specification for the expected arguments and returns a structured object with the parsed options and positionals.

import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []const { parseArgs } = require('node:util');
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []拷贝

parseArgs tokens#

详细的解析信息可用于通过在配置中指定 tokens: true 添加自定义行为。返回的令牌具有描述的属性：

¥Detailed parse information is available for adding custom behaviors by specifying tokens: true in the configuration. The returned tokens have properties describing:

• 所有令牌

  ¥all tokens

  • kind <string> '选项'、'positional' 或 'option-terminator' 之一。

    ¥kind <string> One of 'option', 'positional', or 'option-terminator'.

  • index <number> args 中包含标记的元素索引。所以令牌的源参数是 args[token.index]。

    ¥index <number> Index of element in args containing token. So the source argument for a token is args[token.index].

• 选项令牌

  ¥option tokens

  • name <string> 选项的长名称。

    ¥name <string> Long name of option.

  • rawName <string> 如何在 args 中使用选项，例如 --foo 的 -f。

    ¥rawName <string> How option used in args, like -f of --foo.

  • value <string> | <undefined> 参数中指定的选项值。布尔选项未定义。

    ¥value <string> | <undefined> Option value specified in args. Undefined for boolean options.

  • inlineValue <boolean> | <undefined> 是否内联指定选项值，如 --foo=bar。

    ¥inlineValue <boolean> | <undefined> Whether option value specified inline, like --foo=bar.

• 位置标记

  ¥positional tokens

  • value <string> args 中位置参数的值（即 args[index]）。

    ¥value <string> The value of the positional argument in args (i.e. args[index]).

• 选项终止令牌

  ¥option-terminator token

返回的令牌按照输入参数中遇到的顺序。在 args 中出现多次的选项每次使用都会产生一个令牌。像 -xy 这样的短选项组扩展为每个选项的令牌。所以 -xxx 产生了三个令牌。

¥The returned tokens are in the order encountered in the input args. Options that appear more than once in args produce a token for each use. Short option groups like -xy expand to a token for each option. So -xxx produces three tokens.

例如，要添加对否定选项（如 --no-color）的支持（当选项为 boolean 类型时，allowNegative 支持该选项），可以重新处理返回的令牌以更改为否定选项存储的值。

¥For example, to add support for a negated option like --no-color (which allowNegative supports when the option is of boolean type), the returned tokens can be reprocessed to change the value stored for the negated option.

import { parseArgs } from 'node:util';

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });const { parseArgs } = require('node:util');

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });拷贝

显示否定选项的示例用法，当一个选项以多种方式使用时，最后一个获胜。

¥Example usage showing negated options, and when an option is used multiple ways then last one wins.

$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false } 拷贝

util.parseEnv(content)#

• content <string>

.env 文件的原始内容。

¥The raw contents of a .env file.

• 返回：<Object>

  ¥Returns: <Object>

给出一个示例 .env 文件：

¥Given an example .env file:

const { parseEnv } = require('node:util');

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }import { parseEnv } from 'node:util';

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }拷贝

util.promisify(original)#

• original <Function>

• 返回：<Function>

  ¥Returns: <Function>

采用遵循常见的错误优先的回调风格的函数（也就是将 (err, value) => ... 回调作为最后一个参数），并返回一个返回 promise 的版本。

¥Takes a function following the common error-first callback style, i.e. taking an (err, value) => ... callback as the last argument, and returns a version that returns promises.

const util = require('node:util');
const fs = require('node:fs');

const stat = util.promisify(fs.stat);
stat('.').then((stats) => {
  // Do something with `stats`
}).catch((error) => {
  // Handle the error.
}); 拷贝

或者，等效地使用 async function：

¥Or, equivalently using async functions:

const util = require('node:util');
const fs = require('node:fs');

const stat = util.promisify(fs.stat);

async function callStat() {
  const stats = await stat('.');
  console.log(`This directory is owned by ${stats.uid}`);
}

callStat(); 拷贝

如果存在 original[util.promisify.custom] 属性，promisify 将返回其值，请参阅 自定义 promise 化函数。

¥If there is an original[util.promisify.custom] property present, promisify will return its value, see Custom promisified functions.

promisify() 假设 original 是在所有情况下都将回调作为其最后一个参数的函数。如果 original 不是函数，则 promisify() 将抛出错误。如果 original 是函数，但其最后一个参数不是错误优先的回调，则它仍然会被传入错误优先的回调作为其最后一个参数。

¥promisify() assumes that original is a function taking a callback as its final argument in all cases. If original is not a function, promisify() will throw an error. If original is a function but its last argument is not an error-first callback, it will still be passed an error-first callback as its last argument.

除非经过特殊处理，否则在类方法或其他使用 this 的方法上使用 promisify() 可能无法按预期工作：

¥Using promisify() on class methods or other methods that use this may not work as expected unless handled specially:

const util = require('node:util');

class Foo {
  constructor() {
    this.a = 42;
  }

  bar(callback) {
    callback(null, this.a);
  }
}

const foo = new Foo();

const naiveBar = util.promisify(foo.bar);
// TypeError: Cannot read property 'a' of undefined
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42' 拷贝

自定义 promise 化函数#

¥Custom promisified functions

使用 util.promisify.custom 符号可以覆盖 util.promisify() 的返回值：

¥Using the util.promisify.custom symbol one can override the return value of util.promisify():

const util = require('node:util');

function doSomething(foo, callback) {
  // ...
}

doSomething[util.promisify.custom] = (foo) => {
  return getPromiseSomehow();
};

const promisified = util.promisify(doSomething);
console.log(promisified === doSomething[util.promisify.custom]);
// prints 'true' 拷贝

这对于原始函数不遵循将错误优先的回调作为最后一个参数的标准格式的情况很有用。

¥This can be useful for cases where the original function does not follow the standard format of taking an error-first callback as the last argument.

例如，对于接受 (foo, onSuccessCallback, onErrorCallback) 的函数：

¥For example, with a function that takes in (foo, onSuccessCallback, onErrorCallback):

doSomething[util.promisify.custom] = (foo) => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject);
  });
}; 拷贝

如果 promisify.custom 已定义但不是函数，则 promisify() 将抛出错误。

¥If promisify.custom is defined but is not a function, promisify() will throw an error.

util.promisify.custom#

• <symbol> 可用于声明函数的自定义 Promisified 变体，请参阅 自定义 promise 化函数。

  ¥<symbol> that can be used to declare custom promisified variants of functions, see Custom promisified functions.

除了可以通过 util.promisify.custom 访问外，这个符号是 全局注册，在任何环境下都可以作为 Symbol.for('nodejs.util.promisify.custom') 访问。

¥In addition to being accessible through util.promisify.custom, this symbol is registered globally and can be accessed in any environment as Symbol.for('nodejs.util.promisify.custom').

例如，对于接受 (foo, onSuccessCallback, onErrorCallback) 的函数：

¥For example, with a function that takes in (foo, onSuccessCallback, onErrorCallback):

const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom');

doSomething[kCustomPromisifiedSymbol] = (foo) => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject);
  });
}; 拷贝

util.stripVTControlCharacters(str)#

• str <string>

• 返回：<string>

  ¥Returns: <string>

返回已删除任何 ANSI 转义码的 str。

¥Returns str with any ANSI escape codes removed.

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
// Prints "value" 拷贝

util.styleText(format, text[, options])#

• format <string> | <Array> util.inspect.colors 中定义的文本格式或文本格式数组。

  ¥format <string> | <Array> A text format or an Array of text formats defined in util.inspect.colors.

• text <string> 要格式化的文本。

  ¥text <string> The text to to be formatted.

• options <Object>

  • validateStream <boolean> 当为 true 时，将检查 stream 是否可以处理颜色。默认值：true。

    ¥validateStream <boolean> When true, stream is checked to see if it can handle colors. Default: true.

  • stream <Stream> 如果可以着色，则将验证流。默认值：process.stdout。

    ¥stream <Stream> A stream that will be validated if it can be colored. Default: process.stdout.

此函数返回考虑到在终端中打印所传递的 format 的格式化文本。它知道终端的功能并根据通过 NO_COLORS、NODE_DISABLE_COLORS 和 FORCE_COLOR 环境变量设置的配置采取行动。

¥This function returns a formatted text considering the format passed for printing in a terminal. It is aware of the terminal's capabilities and acts according to the configuration set via NO_COLORS, NODE_DISABLE_COLORS and FORCE_COLOR environment variables.

import { styleText } from 'node:util';
import { stderr } from 'node:process';

const successMessage = styleText('green', 'Success!');
console.log(successMessage);

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Validate if process.stderr has TTY
  { stream: stderr },
);
console.error(successMessage);const { styleText } = require('node:util');
const { stderr } = require('node:process');

const successMessage = styleText('green', 'Success!');
console.log(successMessage);

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // Validate if process.stderr has TTY
  { stream: stderr },
);
console.error(successMessage);拷贝

util.inspect.colors 还提供 italic 和 underline 等文本格式，你可以将两者结合起来：

¥util.inspect.colors also provides text formats such as italic, and underline and you can combine both:

console.log(
  util.styleText(['underline', 'italic'], 'My italic underlined message'),
); 拷贝

传递格式数组时，应用的格式顺序是从左到右，因此后面的样式可能会覆盖前一个样式。

¥When passing an array of formats, the order of the format applied is left to right so the following style might overwrite the previous one.

console.log(
  util.styleText(['red', 'green'], 'text'), // green
); 拷贝

完整的格式列表可以在 modifiers 中找到。

¥The full list of formats can be found in modifiers.

类：util.TextDecoder#

¥Class: util.TextDecoder

WHATWG 编码标准 TextDecoder API 的实现。

¥An implementation of the WHATWG Encoding Standard TextDecoder API.

const decoder = new TextDecoder();
const u8arr = new Uint8Array([72, 101, 108, 108, 111]);
console.log(decoder.decode(u8arr)); // Hello 拷贝

WHATWG 支持的编码#

¥WHATWG supported encodings

根据 WHATWG 编码标准，下表概述了 TextDecoder API 支持的编码。对于每种编码，可以使用一个或多个别名。

¥Per the WHATWG Encoding Standard, the encodings supported by the TextDecoder API are outlined in the tables below. For each encoding, one or more aliases may be used.

不同的 Node.js 构建配置支持不同的编码集。（见 国际化）

¥Different Node.js build configurations support different sets of encodings. (see Internationalization)

默认支持的编码（具有完整的 ICU 数据）#

¥Encodings supported by default (with full ICU data)

使用 small-icu 选项构建 Node.js 时支持的编码#

¥Encodings supported when Node.js is built with the small-icu option

禁用 ICU 时支持的编码#

¥Encodings supported when ICU is disabled

不支持 WHATWG 编码标准 中列出的 'iso-8859-16' 编码。

¥The 'iso-8859-16' encoding listed in the WHATWG Encoding Standard is not supported.

new TextDecoder([encoding[, options]])#

• encoding <string> 标识此 TextDecoder 实例支持的 encoding。默认值：'utf-8'。

  ¥encoding <string> Identifies the encoding that this TextDecoder instance supports. Default: 'utf-8'.

• options <Object>

  • fatal <boolean> 如果解码失败是致命的，则为 true。禁用 ICU 时不支持此选项（请参阅 国际化）。默认值：false。

    ¥fatal <boolean> true if decoding failures are fatal. This option is not supported when ICU is disabled (see Internationalization). Default: false.

  • ignoreBOM <boolean> 当 true 时，TextDecoder 将在解码结果中包含字节顺序标记。当 false 时，字节顺序标记将从输出中删除。此选项仅在 encoding 为 'utf-8'、'utf-16be' 或 'utf-16le' 时使用。默认值：false。

    ¥ignoreBOM <boolean> When true, the TextDecoder will include the byte order mark in the decoded result. When false, the byte order mark will be removed from the output. This option is only used when encoding is 'utf-8', 'utf-16be', or 'utf-16le'. Default: false.

创建新的 TextDecoder 实例。encoding 可以指定支持的编码之一或别名。

¥Creates a new TextDecoder instance. The encoding may specify one of the supported encodings or an alias.

TextDecoder 类也在全局对象上可用。

¥The TextDecoder class is also available on the global object.

textDecoder.decode([input[, options]])#

• input <ArrayBuffer> | <DataView> | <TypedArray> 包含编码数据的 ArrayBuffer、DataView 或 TypedArray 实例。

  ¥input <ArrayBuffer> | <DataView> | <TypedArray> An ArrayBuffer, DataView, or TypedArray instance containing the encoded data.

• options <Object>

  • stream <boolean> true（如果需要额外的数据块）。默认值：false。

    ¥stream <boolean> true if additional chunks of data are expected. Default: false.

• 返回：<string>

  ¥Returns: <string>

解码 input 并返回字符串。如果 options.stream 是 true，则在 input 末尾出现的任何不完整的字节序列都会在内部缓冲并在下一次调用 textDecoder.decode() 后触发。

¥Decodes the input and returns a string. If options.stream is true, any incomplete byte sequences occurring at the end of the input are buffered internally and emitted after the next call to textDecoder.decode().

如果 textDecoder.fatal 是 true，则发生的解码错误将导致抛出 TypeError。

¥If textDecoder.fatal is true, decoding errors that occur will result in a TypeError being thrown.

textDecoder.encoding#

• <string>

TextDecoder 实例支持的编码。

¥The encoding supported by the TextDecoder instance.

textDecoder.fatal#

• <boolean>

如果解码错误导致抛出 TypeError，则该值将为 true。

¥The value will be true if decoding errors result in a TypeError being thrown.

textDecoder.ignoreBOM#

• <boolean>

如果解码结果将包含字节顺序标记，则该值将为 true。

¥The value will be true if the decoding result will include the byte order mark.

类：util.TextEncoder#

¥Class: util.TextEncoder

WHATWG 编码标准 TextEncoder API 的实现。TextEncoder 的所有实例仅支持 UTF-8 编码。

¥An implementation of the WHATWG Encoding Standard TextEncoder API. All instances of TextEncoder only support UTF-8 encoding.

const encoder = new TextEncoder();
const uint8array = encoder.encode('this is some data'); 拷贝

TextEncoder 类也在全局对象上可用。

¥The TextEncoder class is also available on the global object.

textEncoder.encode([input])#

• input <string> 要编码的文本。默认值：一个空字符串。

  ¥input <string> The text to encode. Default: an empty string.

• 返回：<Uint8Array>

  ¥Returns: <Uint8Array>

对 input 字符串进行 UTF-8 编码并返回包含编码字节的 Uint8Array。

¥UTF-8 encodes the input string and returns a Uint8Array containing the encoded bytes.

textEncoder.encodeInto(src, dest)#

• src <string> 要编码的文本。

  ¥src <string> The text to encode.

• dest <Uint8Array> 保存编码结果的数组。

  ¥dest <Uint8Array> The array to hold the encode result.

• 返回：<Object>

  ¥Returns: <Object>

  • read <number> 读取的来源的 Unicode 代码单元。

    ¥read <number> The read Unicode code units of src.

  • written <number> 写入的目标的 UTF-8 字节。

    ¥written <number> The written UTF-8 bytes of dest.

将 src 字符串 UTF-8 编码为 dest Uint8Array 并返回包含读取的 Unicode 代码单元和写入的 UTF-8 字节的对象。

¥UTF-8 encodes the src string to the dest Uint8Array and returns an object containing the read Unicode code units and written UTF-8 bytes.

const encoder = new TextEncoder();
const src = 'this is some data';
const dest = new Uint8Array(10);
const { read, written } = encoder.encodeInto(src, dest); 拷贝

textEncoder.encoding#

• <string>

TextEncoder 实例支持的编码。始终设置为 'utf-8'。

¥The encoding supported by the TextEncoder instance. Always set to 'utf-8'.

util.toUSVString(string)#

• string <string>

在用 Unicode "替换字符" U+FFFD 替换任何代理代码点（或等效地，任何未配对的代理代码单元）后返回 string。

¥Returns the string after replacing any surrogate code points (or equivalently, any unpaired surrogate code units) with the Unicode "replacement character" U+FFFD.

util.transferableAbortController()#

创建并返回一个 <AbortController> 实例，其 <AbortSignal> 被标记为可转让，可与 structuredClone() 或 postMessage() 一起使用。

¥Creates and returns an <AbortController> instance whose <AbortSignal> is marked as transferable and can be used with structuredClone() or postMessage().

util.transferableAbortSignal(signal)#

• signal <AbortSignal>

• 返回：<AbortSignal>

  ¥Returns: <AbortSignal>

将给定的 <AbortSignal> 标记为可转让，以便它可以与 structuredClone() 和 postMessage() 一起使用。

¥Marks the given <AbortSignal> as transferable so that it can be used with structuredClone() and postMessage().

const signal = transferableAbortSignal(AbortSignal.timeout(100));
const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]); 拷贝

util.aborted(signal, resource)#

• signal <AbortSignal>

• resource <Object> 任何非空实体，对其的引用是弱引用的。

  ¥resource <Object> Any non-null entity, reference to which is held weakly.

• 返回：<Promise>

  ¥Returns: <Promise>

在提供的 signal 上监听中止事件，并返回在 signal 中止时履行的 promise。如果传递的 resource 在 signal 中止之前被垃圾收集，则返回的 promise 将无限期地保持挂起状态。

¥Listens to abort event on the provided signal and returns a promise that is fulfilled when the signal is aborted. If the passed resource is garbage collected before the signal is aborted, the returned promise shall remain pending indefinitely.

const { aborted } = require('node:util');

const dependent = obtainSomethingAbortable();

aborted(dependent.signal, dependent).then(() => {
  // Do something when dependent is aborted.
});

dependent.on('event', () => {
  dependent.abort();
});import { aborted } from 'node:util';

const dependent = obtainSomethingAbortable();

aborted(dependent.signal, dependent).then(() => {
  // Do something when dependent is aborted.
});

dependent.on('event', () => {
  dependent.abort();
});拷贝

util.types#

util.types 为不同种类的内置对象提供类型检查。与 instanceof 或 Object.prototype.toString.call(value) 不同，这些检查不检查可从 JavaScript 访问的对象的属性（如它们的原型），并且通常具有调用 C++ 的开销。

¥util.types provides type checks for different kinds of built-in objects. Unlike instanceof or Object.prototype.toString.call(value), these checks do not inspect properties of the object that are accessible from JavaScript (like their prototype), and usually have the overhead of calling into C++.

结果通常不会对值在 JavaScript 中公开的属性或行为类型做出任何保证。它们主要对喜欢在 JavaScript 中进行类型检查的插件开发者有用。

¥The result generally does not make any guarantees about what kinds of properties or behavior a value exposes in JavaScript. They are primarily useful for addon developers who prefer to do type checking in JavaScript.

API 可通过 require('node:util').types 或 require('node:util/types') 访问。

¥The API is accessible via require('node:util').types or require('node:util/types').

util.types.isAnyArrayBuffer(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 ArrayBuffer 或 SharedArrayBuffer 实例，则返回 true。

¥Returns true if the value is a built-in ArrayBuffer or SharedArrayBuffer instance.

另见 util.types.isArrayBuffer() 和 util.types.isSharedArrayBuffer()。

¥See also util.types.isArrayBuffer() and util.types.isSharedArrayBuffer().

util.types.isAnyArrayBuffer(new ArrayBuffer());  // Returns true
util.types.isAnyArrayBuffer(new SharedArrayBuffer());  // Returns true 拷贝

util.types.isArrayBufferView(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是 ArrayBuffer 视图之一的实例，例如类型化数组对象或 DataView，则返回 true。相当于 ArrayBuffer.isView()。

¥Returns true if the value is an instance of one of the ArrayBuffer views, such as typed array objects or DataView. Equivalent to ArrayBuffer.isView().

util.types.isArrayBufferView(new Int8Array());  // true
util.types.isArrayBufferView(Buffer.from('hello world')); // true
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16)));  // true
util.types.isArrayBufferView(new ArrayBuffer());  // false 拷贝

util.types.isArgumentsObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为 arguments 对象，则返回 true。

¥Returns true if the value is an arguments object.

function foo() {
  util.types.isArgumentsObject(arguments);  // Returns true
} 拷贝

util.types.isArrayBuffer(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 ArrayBuffer 实例，则返回 true。这不包括 SharedArrayBuffer 个实例。通常，最好对两者都进行测试；参见 util.types.isAnyArrayBuffer()。

¥Returns true if the value is a built-in ArrayBuffer instance. This does not include SharedArrayBuffer instances. Usually, it is desirable to test for both; See util.types.isAnyArrayBuffer() for that.

util.types.isArrayBuffer(new ArrayBuffer());  // Returns true
util.types.isArrayBuffer(new SharedArrayBuffer());  // Returns false 拷贝

util.types.isAsyncFunction(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为 异步函数，则返回 true。这只会报告 JavaScript 引擎看到的内容；特别是，如果使用了转译工具，返回值可能与原始源代码不匹配。

¥Returns true if the value is an async function. This only reports back what the JavaScript engine is seeing; in particular, the return value may not match the original source code if a transpilation tool was used.

util.types.isAsyncFunction(function foo() {});  // Returns false
util.types.isAsyncFunction(async function foo() {});  // Returns true 拷贝

util.types.isBigInt64Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为 BigInt64Array 实例，则返回 true。

¥Returns true if the value is a BigInt64Array instance.

util.types.isBigInt64Array(new BigInt64Array());   // Returns true
util.types.isBigInt64Array(new BigUint64Array());  // Returns false 拷贝

util.types.isBigUint64Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为 BigUint64Array 实例，则返回 true。

¥Returns true if the value is a BigUint64Array instance.

util.types.isBigUint64Array(new BigInt64Array());   // Returns false
util.types.isBigUint64Array(new BigUint64Array());  // Returns true 拷贝

util.types.isBooleanObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是布尔对象（例如由 new Boolean() 创建），则返回 true。

¥Returns true if the value is a boolean object, e.g. created by new Boolean().

util.types.isBooleanObject(false);  // Returns false
util.types.isBooleanObject(true);   // Returns false
util.types.isBooleanObject(new Boolean(false)); // Returns true
util.types.isBooleanObject(new Boolean(true));  // Returns true
util.types.isBooleanObject(Boolean(false)); // Returns false
util.types.isBooleanObject(Boolean(true));  // Returns false 拷贝

util.types.isBoxedPrimitive(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是任何封装的原始对象（例如由 new Boolean()、new String() 或 Object(Symbol()) 创建），则返回 true。

¥Returns true if the value is any boxed primitive object, e.g. created by new Boolean(), new String() or Object(Symbol()).

例如：

¥For example:

util.types.isBoxedPrimitive(false); // Returns false
util.types.isBoxedPrimitive(new Boolean(false)); // Returns true
util.types.isBoxedPrimitive(Symbol('foo')); // Returns false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true
util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true 拷贝

util.types.isCryptoKey(value)#

• value <Object>

• 返回：<boolean>

  ¥Returns: <boolean>

如果 value 是 <CryptoKey>，则返回 true，否则返回 false。

¥Returns true if value is a <CryptoKey>, false otherwise.

util.types.isDataView(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 DataView 实例，则返回 true。

¥Returns true if the value is a built-in DataView instance.

const ab = new ArrayBuffer(20);
util.types.isDataView(new DataView(ab));  // Returns true
util.types.isDataView(new Float64Array());  // Returns false 拷贝

另见 ArrayBuffer.isView()。

¥See also ArrayBuffer.isView().

util.types.isDate(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Date 实例，则返回 true。

¥Returns true if the value is a built-in Date instance.

util.types.isDate(new Date());  // Returns true 拷贝

util.types.isExternal(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是原生的 External 值，则返回 true。

¥Returns true if the value is a native External value.

原生的 External 值是特殊类型的对象，它包含用于从原生代码访问的原始 C++ 指针 (void*)，并且没有其他属性。此类对象由 Node.js 内部或原生插件创建。在 JavaScript 中，它们是具有 null 原型的 frozen 对象。

¥A native External value is a special type of object that contains a raw C++ pointer (void*) for access from native code, and has no other properties. Such objects are created either by Node.js internals or native addons. In JavaScript, they are frozen objects with a null prototype.

#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
  int* raw = (int*) malloc(1024);
  napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
  if (status != napi_ok) {
    napi_throw_error(env, NULL, "napi_create_external failed");
    return NULL;
  }
  return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
... 拷贝

const native = require('napi_addon.node');
const data = native.myNapi();
util.types.isExternal(data); // returns true
util.types.isExternal(0); // returns false
util.types.isExternal(new String('foo')); // returns false 拷贝

有关 napi_create_external 的更多信息，请参阅 napi_create_external()。

¥For further information on napi_create_external, refer to napi_create_external().

util.types.isFloat32Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Float32Array 实例，则返回 true。

¥Returns true if the value is a built-in Float32Array instance.

util.types.isFloat32Array(new ArrayBuffer());  // Returns false
util.types.isFloat32Array(new Float32Array());  // Returns true
util.types.isFloat32Array(new Float64Array());  // Returns false 拷贝

util.types.isFloat64Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Float64Array 实例，则返回 true。

¥Returns true if the value is a built-in Float64Array instance.

util.types.isFloat64Array(new ArrayBuffer());  // Returns false
util.types.isFloat64Array(new Uint8Array());  // Returns false
util.types.isFloat64Array(new Float64Array());  // Returns true 拷贝

util.types.isGeneratorFunction(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是生成器函数，则返回 true。这只会报告 JavaScript 引擎看到的内容；特别是，如果使用了转译工具，返回值可能与原始源代码不匹配。

¥Returns true if the value is a generator function. This only reports back what the JavaScript engine is seeing; in particular, the return value may not match the original source code if a transpilation tool was used.

util.types.isGeneratorFunction(function foo() {});  // Returns false
util.types.isGeneratorFunction(function* foo() {});  // Returns true 拷贝

util.types.isGeneratorObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是从内置的生成器函数返回的生成器对象，则返回 true。这只会报告 JavaScript 引擎看到的内容；特别是，如果使用了转译工具，返回值可能与原始源代码不匹配。

¥Returns true if the value is a generator object as returned from a built-in generator function. This only reports back what the JavaScript engine is seeing; in particular, the return value may not match the original source code if a transpilation tool was used.

function* foo() {}
const generator = foo();
util.types.isGeneratorObject(generator);  // Returns true 拷贝

util.types.isInt8Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Int8Array 实例，则返回 true。

¥Returns true if the value is a built-in Int8Array instance.

util.types.isInt8Array(new ArrayBuffer());  // Returns false
util.types.isInt8Array(new Int8Array());  // Returns true
util.types.isInt8Array(new Float64Array());  // Returns false 拷贝

util.types.isInt16Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Int16Array 实例，则返回 true。

¥Returns true if the value is a built-in Int16Array instance.

util.types.isInt16Array(new ArrayBuffer());  // Returns false
util.types.isInt16Array(new Int16Array());  // Returns true
util.types.isInt16Array(new Float64Array());  // Returns false 拷贝

util.types.isInt32Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Int32Array 实例，则返回 true。

¥Returns true if the value is a built-in Int32Array instance.

util.types.isInt32Array(new ArrayBuffer());  // Returns false
util.types.isInt32Array(new Int32Array());  // Returns true
util.types.isInt32Array(new Float64Array());  // Returns false 拷贝

util.types.isKeyObject(value)#

• value <Object>

• 返回：<boolean>

  ¥Returns: <boolean>

如果 value 是 <KeyObject>，则返回 true，否则返回 false。

¥Returns true if value is a <KeyObject>, false otherwise.

util.types.isMap(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Map 实例，则返回 true。

¥Returns true if the value is a built-in Map instance.

util.types.isMap(new Map());  // Returns true 拷贝

util.types.isMapIterator(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是为内置的 Map 实例返回的迭代器，则返回 true。

¥Returns true if the value is an iterator returned for a built-in Map instance.

const map = new Map();
util.types.isMapIterator(map.keys());  // Returns true
util.types.isMapIterator(map.values());  // Returns true
util.types.isMapIterator(map.entries());  // Returns true
util.types.isMapIterator(map[Symbol.iterator]());  // Returns true 拷贝

util.types.isModuleNamespaceObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是 模块命名空间对象 的实例，则返回 true。

¥Returns true if the value is an instance of a Module Namespace Object.

import * as ns from './a.js';

util.types.isModuleNamespaceObject(ns);  // Returns true 拷贝

util.types.isNativeError(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值由 内置 Error 类型 的构造函数返回，则返回 true。

¥Returns true if the value was returned by the constructor of a built-in Error type.

console.log(util.types.isNativeError(new Error()));  // true
console.log(util.types.isNativeError(new TypeError()));  // true
console.log(util.types.isNativeError(new RangeError()));  // true 拷贝

原生错误类型的子类也是原生错误：

¥Subclasses of the native error types are also native errors:

class MyError extends Error {}
console.log(util.types.isNativeError(new MyError()));  // true 拷贝

作为原生错误类的 instanceof 值不等同于 isNativeError() 为该值返回 true。isNativeError() 为来自不同 realm 的错误返回 true，而 instanceof Error 为这些错误返回 false：

¥A value being instanceof a native error class is not equivalent to isNativeError() returning true for that value. isNativeError() returns true for errors which come from a different realm while instanceof Error returns false for these errors:

const vm = require('node:vm');
const context = vm.createContext({});
const myError = vm.runInContext('new Error()', context);
console.log(util.types.isNativeError(myError)); // true
console.log(myError instanceof Error); // false 拷贝

相反，对于原生错误的构造函数未返回的所有对象，isNativeError() 返回 false。这包括 instanceof 原生错误的值：

¥Conversely, isNativeError() returns false for all objects which were not returned by the constructor of a native error. That includes values which are instanceof native errors:

const myError = { __proto__: Error.prototype };
console.log(util.types.isNativeError(myError)); // false
console.log(myError instanceof Error); // true 拷贝

util.types.isNumberObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是数字对象（例如由 new Number() 创建），则返回 true。

¥Returns true if the value is a number object, e.g. created by new Number().

util.types.isNumberObject(0);  // Returns false
util.types.isNumberObject(new Number(0));   // Returns true 拷贝

util.types.isPromise(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Promise，则返回 true。

¥Returns true if the value is a built-in Promise.

util.types.isPromise(Promise.resolve(42));  // Returns true 拷贝

util.types.isProxy(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为 Proxy 实例，则返回 true。

¥Returns true if the value is a Proxy instance.

const target = {};
const proxy = new Proxy(target, {});
util.types.isProxy(target);  // Returns false
util.types.isProxy(proxy);  // Returns true 拷贝

util.types.isRegExp(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是正则表达式对象，则返回 true。

¥Returns true if the value is a regular expression object.

util.types.isRegExp(/abc/);  // Returns true
util.types.isRegExp(new RegExp('abc'));  // Returns true 拷贝

util.types.isSet(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Set 实例，则返回 true。

¥Returns true if the value is a built-in Set instance.

util.types.isSet(new Set());  // Returns true 拷贝

util.types.isSetIterator(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是为内置的 Set 实例返回的迭代器，则返回 true。

¥Returns true if the value is an iterator returned for a built-in Set instance.

const set = new Set();
util.types.isSetIterator(set.keys());  // Returns true
util.types.isSetIterator(set.values());  // Returns true
util.types.isSetIterator(set.entries());  // Returns true
util.types.isSetIterator(set[Symbol.iterator]());  // Returns true 拷贝

util.types.isSharedArrayBuffer(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 SharedArrayBuffer 实例，则返回 true。这不包括 ArrayBuffer 个实例。通常，最好对两者都进行测试；参见 util.types.isAnyArrayBuffer()。

¥Returns true if the value is a built-in SharedArrayBuffer instance. This does not include ArrayBuffer instances. Usually, it is desirable to test for both; See util.types.isAnyArrayBuffer() for that.

util.types.isSharedArrayBuffer(new ArrayBuffer());  // Returns false
util.types.isSharedArrayBuffer(new SharedArrayBuffer());  // Returns true 拷贝

util.types.isStringObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是字符串对象（例如由 new String() 创建），则返回 true。

¥Returns true if the value is a string object, e.g. created by new String().

util.types.isStringObject('foo');  // Returns false
util.types.isStringObject(new String('foo'));   // Returns true 拷贝

util.types.isSymbolObject(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值是符号对象（通过在 Symbol 原始类型上调用 Object() 创建），则返回 true。

¥Returns true if the value is a symbol object, created by calling Object() on a Symbol primitive.

const symbol = Symbol('foo');
util.types.isSymbolObject(symbol);  // Returns false
util.types.isSymbolObject(Object(symbol));   // Returns true 拷贝

util.types.isTypedArray(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 TypedArray 实例，则返回 true。

¥Returns true if the value is a built-in TypedArray instance.

util.types.isTypedArray(new ArrayBuffer());  // Returns false
util.types.isTypedArray(new Uint8Array());  // Returns true
util.types.isTypedArray(new Float64Array());  // Returns true 拷贝

另见 ArrayBuffer.isView()。

¥See also ArrayBuffer.isView().

util.types.isUint8Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Uint8Array 实例，则返回 true。

¥Returns true if the value is a built-in Uint8Array instance.

util.types.isUint8Array(new ArrayBuffer());  // Returns false
util.types.isUint8Array(new Uint8Array());  // Returns true
util.types.isUint8Array(new Float64Array());  // Returns false 拷贝

util.types.isUint8ClampedArray(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Uint8ClampedArray 实例，则返回 true。

¥Returns true if the value is a built-in Uint8ClampedArray instance.

util.types.isUint8ClampedArray(new ArrayBuffer());  // Returns false
util.types.isUint8ClampedArray(new Uint8ClampedArray());  // Returns true
util.types.isUint8ClampedArray(new Float64Array());  // Returns false 拷贝

util.types.isUint16Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Uint16Array 实例，则返回 true。

¥Returns true if the value is a built-in Uint16Array instance.

util.types.isUint16Array(new ArrayBuffer());  // Returns false
util.types.isUint16Array(new Uint16Array());  // Returns true
util.types.isUint16Array(new Float64Array());  // Returns false 拷贝

util.types.isUint32Array(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 Uint32Array 实例，则返回 true。

¥Returns true if the value is a built-in Uint32Array instance.

util.types.isUint32Array(new ArrayBuffer());  // Returns false
util.types.isUint32Array(new Uint32Array());  // Returns true
util.types.isUint32Array(new Float64Array());  // Returns false 拷贝

util.types.isWeakMap(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 WeakMap 实例，则返回 true。

¥Returns true if the value is a built-in WeakMap instance.

util.types.isWeakMap(new WeakMap());  // Returns true 拷贝

util.types.isWeakSet(value)#

• value <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果值为内置的 WeakSet 实例，则返回 true。

¥Returns true if the value is a built-in WeakSet instance.

util.types.isWeakSet(new WeakSet());  // Returns true 拷贝

弃用的 API#

¥Deprecated APIs

以下 API 已弃用，不应再使用。应更新现有应用和模块以寻找替代方法。

¥The following APIs are deprecated and should no longer be used. Existing applications and modules should be updated to find alternative approaches.

util._extend(target, source)#

• target <Object>

• source <Object>

util._extend() 方法从未打算在内部的 Node.js 模块之外使用。社区无论如何都找到并使用了它。

¥The util._extend() method was never intended to be used outside of internal Node.js modules. The community found and used it anyway.

它已被弃用，不应在新代码中使用。JavaScript 通过 Object.assign() 提供了非常相似的内置功能。

¥It is deprecated and should not be used in new code. JavaScript comes with very similar built-in functionality through Object.assign().

util.isArray(object)#

• object <any>

• 返回：<boolean>

  ¥Returns: <boolean>

Array.isArray() 的别名。

¥Alias for Array.isArray().

如果给定的 object 是 Array，则返回 true。否则，返回 false。

¥Returns true if the given object is an Array. Otherwise, returns false.

const util = require('node:util');

util.isArray([]);
// Returns: true
util.isArray(new Array());
// Returns: true
util.isArray({});
// Returns: false 拷贝

util.isBoolean(object)#

• object <any>

• 返回：<boolean>

  ¥Returns: <boolean>

如果给定的 object 是 Boolean，则返回 true。否则，返回 false。

¥Returns true if the given object is a Boolean. Otherwise, returns false.

const util = require('node:util');

util.isBoolean(1);
// Returns: false
util.isBoolean(0);
// Returns: false
util.isBoolean(false);
// Returns: true 拷贝

util.isBuffer(object)#