Node.js v22.22.0 文档

util.callbackify(original)#>

• original <Function> 一个 async 函数
• 返回：<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.】

import { callbackify } from 'node:util';

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

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
});const { callbackify } = require('node:util');

async function fn() {
  return 'hello world';
}
const callbackFunction = 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 函数的应用部分。
• callback <Function> 第一次调用日志函数时，如果传入的参数是一个更优化的日志函数，就会调用该回调。
• 返回: <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.】

import { debuglog } from 'node:util';
const log = debuglog('foo');

log('hello from foo [%d]', 123);const { debuglog } = require('node:util');
const log = debuglog('foo');

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:】

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:】

import { debuglog } from 'node:util';
const log = debuglog('foo');

log('hi there, it\'s foo-bar [%d]', 2333);const { debuglog } = require('node:util');
const log = debuglog('foo');

log('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.】

import { debuglog } from 'node:util';
let log = debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  log = debug;
});const { debuglog } = require('node:util');
let log = debuglog('internals', (debug) => {
  // Replace with a logging function that optimizes out
  // testing if the section is enabled
  log = 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.】

import { debuglog } from 'node:util';
const enabled = debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
}const { debuglog } = require('node:util');
const enabled = 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> 正在被弃用的函数。
• msg <string> 当调用已弃用的函数时显示的警告信息。
• code <string> 一个弃用代码。有关代码列表，请参阅 已弃用的 API 列表。
• 返回值：<Function> 已弃用的函数，会发出警告。

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.】

import { deprecate } from 'node:util';

export const obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');const { deprecate } = require('node:util');

exports.obsoleteFunction = 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.】

import { deprecate } from 'node:util';

const fn1 = deprecate(
  () => 'a value',
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  () => 'a  different value',
  'other dep message',
  'DEP0001',
);
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same codeconst { deprecate } = require('node:util');

const fn1 = deprecate(
  function() {
    return 'a value';
  },
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  function() {
    return 'a  different value';
  },
  'other dep message',
  '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.diff(actual, expected)#>

• actual <Array> | <string> 要比较的第一个值
• expected <Array> | <string> 要比较的第二个值
• 返回：<Array> 差异条目的数组。每个条目是一个包含两个元素的数组：
  • 0 <number> 操作代码：-1 删除，0 无操作/未更改，1 插入
  • 1 <string> 与操作相关的值
• 算法复杂度：O(N*D)，其中：
• N 是两个序列合并后的总长度 (N = actual.length + expected.length)
• D 是编辑距离（将一个序列转换为另一个序列所需的最少操作次数）。

util.diff() 比较两个字符串或数组值，并返回一个差异条目的数组。它使用 Myers 差异算法来计算最小差异，这也是断言错误消息内部使用的算法。

如果值相等，则返回一个空数组。

【If the values are equal, an empty array is returned.】

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

// Comparing strings
const actualString = '12345678';
const expectedString = '12!!5!7!';
console.log(diff(actualString, expectedString));
// [
//   [0, '1'],
//   [0, '2'],
//   [1, '3'],
//   [1, '4'],
//   [-1, '!'],
//   [-1, '!'],
//   [0, '5'],
//   [1, '6'],
//   [-1, '!'],
//   [0, '7'],
//   [1, '8'],
//   [-1, '!'],
// ]
// Comparing arrays
const actualArray = ['1', '2', '3'];
const expectedArray = ['1', '3', '4'];
console.log(diff(actualArray, expectedArray));
// [
//   [0, '1'],
//   [1, '2'],
//   [0, '3'],
//   [-1, '4'],
// ]
// Equal values return empty array
console.log(diff('same', 'same'));
// [] 拷贝

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

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

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 函数或 Symbol.toPrimitive 函数的对象将使用 util.inspect() 进行检查，选项为 { depth: 0, colors: false, compact: 3 }。
• %d：Number 将用于转换除 BigInt 和 Symbol 之外的所有值。
• %i：parseInt(value, 10) 用于除 BigInt 和 Symbol 之外的所有值。
• %f：parseFloat(value) 用于除了 Symbol 之外的所有值。
• %j：JSON。如果参数包含循环引用，则替换为字符串 '[Circular]'。
• %o：Object。对象的字符串表示，使用通用的 JavaScript 对象格式。类似于 util.inspect()，选项为 { showHidden: true, showProxy: true }。这将显示包括不可枚举属性和代理在内的完整对象。
• %O：Object。对象的字符串表示形式，采用通用的 JavaScript 对象格式。类似于不带选项的 util.inspect()。这将显示完整的对象，但不包括不可枚举属性和代理。
• %c：CSS。此说明符会被忽略，并且会跳过传入的任何 CSS。
• %%：单个百分号（'%'）。这不消耗任何参数。
• 返回值：<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.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.getCallSites([frameCount][, options])#>

• frameCount <number> 可选的要捕获为调用点对象的帧数。默认值： 10。允许范围为 1 到 200。
• options <Object> 可选
  • sourceMap <boolean> 从源映射重建堆栈跟踪中的原始位置。 默认情况下通过标志 --enable-source-maps 启用。
• 返回值：<Object[]> 一个调用站点对象数组
  • functionName <string> 返回与此调用点关联的函数的名称。
  • scriptName <string> 返回包含此调用点对应函数脚本的资源名称。
  • scriptId <string> 返回脚本的唯一 ID，如同在 Chrome DevTools 协议 Runtime.ScriptId 中一样。
  • lineNumber <number> 返回 JavaScript 脚本的行号（从 1 开始）。
  • columnNumber <number> 返回 JavaScript 脚本的列号（从 1 开始）。

返回一个包含调用者函数堆栈的调用点对象数组。

【Returns an array of call site objects containing the stack of the caller function.】

import { getCallSites } from 'node:util';

function exampleFunction() {
  const callSites = getCallSites();

  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();const { getCallSites } = require('node:util');

function exampleFunction() {
  const callSites = getCallSites();

  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();拷贝

通过将选项 sourceMap 设置为 true，可以重建原始位置。 如果源映射不可用，原始位置将与当前位置相同。 当启用 --enable-source-maps 标志时，例如使用 --experimental-transform-types，sourceMap 将默认为 true。

【It is possible to reconstruct the original locations by setting the option sourceMap to true. If the source map is not available, the original location will be the same as the current location. When the --enable-source-maps flag is enabled, for example when using --experimental-transform-types, sourceMap will be true by default.】

import { getCallSites } from 'node:util';

interface Foo {
  foo: string;
}

const callSites = getCallSites({ sourceMap: true });

// With sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26 拷贝

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

const callSites = getCallSites({ sourceMap: true });

// With sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 7
// Column Number: 26

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26 拷贝

util.getSystemErrorName(err)#>

• err <number>
• 返回：<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>

返回一个包含 Node.js API 提供的所有系统错误代码的 Map。错误代码与错误名称之间的映射依赖于平台。有关常见错误的名称，请参见 常见系统错误。

【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.getSystemErrorMessage(err)#>

• err <number>
• 返回：<string>

返回来自 Node.js API 的数字错误代码对应的字符串信息。错误代码与字符串信息之间的映射取决于平台。

【Returns the string message for a numeric error code that comes from a Node.js API. The mapping between error codes and string messages is platform-dependent.】

fs.access('file/that/does/not/exist', (err) => {
  const message = util.getSystemErrorMessage(err.errno);
  console.error(message);  // No such file or directory
}); 拷贝

util.setTraceSigInt(enable)#>

• enable <boolean>

启用或禁用在 SIGINT 信号时打印堆栈跟踪。该 API 仅在主线程上可用。

【Enable or disable printing a stack trace on SIGINT. The API is only available on the main thread.】

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.】

将一个 function Object() [native code] 的原型方法继承到另一个中。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:】

import EventEmitter from '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');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。
• options <Object>
  • showHidden <boolean> 如果为 true，则 object 的非枚举符号和属性会包含在格式化结果中。WeakMap 和 WeakSet 条目也会被包含，以及用户定义的原型属性（不包括方法属性）。默认值： false。
  • depth <number> 指定在格式化 object 时递归的次数。这对于检查大型对象很有用。要递归到最大调用堆栈大小，请传入 Infinity 或 null。默认值： 2。
  • colors <boolean> 如果为 true，输出将使用 ANSI 颜色代码进行样式化。颜色是可自定义的。参见 自定义 util.inspect 颜色。 默认值: false。
  • customInspect <boolean> 如果为 false，[util.inspect.custom](depth, opts, inspect) 函数将不会被调用。默认值： true。
  • showProxy <boolean> 如果为 true，Proxy 检查将包括 target 和 handler 对象。默认值： false。
  • maxArrayLength <integer> 指定在格式化时包含的 Array、<TypedArray>、<Map>、WeakMap 和 WeakSet 元素的最大数量。设置为 null 或 Infinity 可显示所有元素。设置为 0 或负数则不显示任何元素。默认值： 100。
  • maxStringLength <integer> 指定格式化时要包含的最大字符数。设置为 null 或 Infinity 以显示所有元素。设置为 0 或负数以不显示任何字符。默认值： 10000。
  • breakLength <integer> 输入值被拆分到多行的长度。设置为 Infinity 可将输入格式化为单行（与 compact 设置为 true 或任何大于等于 1 的数字一起使用）。默认值: 80。
  • compact <boolean> | <integer> 将此设置为 false 会导致每个对象键显示在新行上。对于长度超过 breakLength 的文本，它将在新行处换行。如果设置为数字，则最多 n 个内部元素会被合并在同一行上，只要所有属性都能适应 breakLength。短数组元素也会被组合在一起。更多信息，请参见下面的示例。默认值： 3。
  • sorted <boolean> | <Function> 如果设置为 true 或一个函数，对象的所有属性以及 Set 和 Map 的条目将在生成的字符串中进行排序。如果设置为 true，将使用 默认排序。如果设置为函数，则将其用作 比较函数。
  • getters <boolean> | <string> 如果设置为 true，则会检查 getter。如果设置为 'get'，则只检查没有对应 setter 的 getter。如果设置为 'set'，则只检查有对应 setter 的 getter。根据 getter 函数的不同，这可能会引起副作用。默认值: false。
  • numericSeparator <boolean> 如果设置为 true，则在所有大整数和数字中，每三位数字之间使用下划线进行分隔。默认值: false。
• 返回：<string> object 的表示。

util.inspect() 方法返回一个 object 的字符串表示形式，旨在用于调试。util.inspect 的输出可能随时更改，不应在程序中依赖。可以传入额外的 options 来改变结果。util.inspect() 会使用构造函数的名称和/或 Symbol.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 Symbol.toStringTag property 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:】

import { inspect } from '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] }
// }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:】

import util from 'node:util';

console.log(util.inspect(util, { showHidden: true, depth: null }));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:】

import { inspect } from '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(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(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.const { inspect } = 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(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(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.】

import { inspect } from '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 } }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().】

import { inspect } from 'node:util';
import assert from '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 }),
);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.】

import { inspect } from 'node:util';

const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;

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_45const { inspect } = require('node:util');

const thousand = 1000;
const million = 1000000;
const bigNumber = 123456789n;
const bigDecimal = 1234.12345;

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 颜色#>

【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 中的颜色关联的映射。

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

【The default styles and associated colors are:】

• bigint: yellow
• boolean：yellow
• date：magenta
• module：underline
• name：（无样式）
• null：bold
• number: yellow
• regexp: red
• special：cyan（例如，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 - 将所有（颜色）修饰符重置为默认值
• 加粗 - 使文字加粗
• 斜体 - 使文本变为斜体
• 下划线 - 使文本带下划线
• 删除线 - 在文字中间加一条水平线（别名：strikeThrough、crossedout、crossedOut）
• hidden - 打印文本，但使其不可见（别名：conceal）
• 暗 - 颜色强度降低（别名：faint）
• 上划线 - 使文本带上划线
• blink - 以一定间隔隐藏和显示文本
• 反转 - 交换前景色和背景色 (别名: swapcolors, swapColors)
• doubleunderline - 将文本设置为双下划线（别名：doubleUnderline）
• 加框 - 在文字周围画一个框

前景色#>

【Foreground colors】

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• gray（别名：grey、blackBright）
• redBright
• greenBright
• yellowBright
• blueBright
• magentaBright
• cyanBright
• whiteBright

背景颜色#>

【Background colors】

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite
• bgGray（别名：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.】

import { inspect } from 'node:util';

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

  [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);

console.log(inspect(box));
// "Box< true >"const { inspect } = require('node:util');

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

  [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);

console.log(inspect(box));
// "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().】

import { inspect } from 'node:util';

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

console.log(inspect(obj));
// "{ bar: 'baz' }"const { inspect } = require('node:util');

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

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

util.inspect.custom#>

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

除了可以通过 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 环境中使用自定义的 inspect 函数，而在浏览器中则被忽略。util.inspect() 函数本身作为第三个参数传递给自定义 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.】

import { inspect } from 'node:util';
const arr = Array(156).fill(0);

console.log(arr); // Logs the truncated array
inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full arrayconst { inspect } = require('node:util');
const arr = Array(156).fill(0);

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

util.isDeepStrictEqual(val1, val2)#>

• val1 <any>
• val2 <any>
• 返回：<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 对象的所有属性都作为类原型上的 getter 和 setter 实现，而不是作为对象自身的数据属性。

【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)#>

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

通过解析 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>

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>

mime.toString() 的别名。

【Alias for mime.toString().】

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

【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()#>

通过创建空参数生成一个新的 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>

返回一个迭代器，用于遍历参数中的每一个名称-值对。迭代器的每一项都是一个 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。

返回名称为 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>

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

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

mimeParams.keys()#>

• 返回：<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 an iterator over the values of each name-value pair.】

mimeParams[Symbol.iterator]()#>

• 返回：<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 支持以下属性：
  • args <string[]> 参数字符串数组。默认值： 移除 execPath 和 filename 后的 process.argv。
  • options <Object> 用于描述解析器已知的参数。options 的键是选项的长名称，值是一个 <Object>，可以包含以下属性：
    • type <string> 参数类型，必须是 boolean 或 string。
    • multiple <boolean> 是否可以多次提供此选项。如果为 true，所有值将被收集到一个数组中。如果为 false，选项的值以最后一次为准。默认值: false。
    • short <string> 该选项的单字符别名。
    • default <string> | <boolean> | <string[]> | <boolean[]> 如果在解析的参数中未出现该选项，则要分配给该选项的值。该值必须与 type 属性指定的类型匹配。如果 multiple 为 true，则它必须是一个数组。当解析的参数中出现该选项时，即使提供的值为假值，也不会应用默认值。
  • strict <boolean> 当遇到未知参数，或传递的参数与 options 中配置的 type 不匹配时，是否应抛出错误。 默认值: true。
  • allowPositionals <boolean> 该命令是否接受位置参数。默认值： 当 strict 为 true 时为 false，否则为 true。
  • allowNegative <boolean> 如果为 true，允许通过在选项名前加 --no- 明确将布尔选项设置为 false。 默认值: false。
  • tokens <boolean> 返回解析后的令牌。这对于扩展内置功能非常有用，从添加额外检查到以不同方式重新处理令牌。 默认值： false。
• 返回: <Object> 解析后的命令行参数：
  • values <Object> 已解析的选项名称与其 <string> 或 <boolean> 值的映射。
  • positionals <string[]> 位置参数。
  • tokens <Object[]> | <undefined> 请参见 parseArgs tokens 部分。只有当 config 包含 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:】

• 所有令牌
  • kind <string> 可选值之一：'option'、'positional' 或 'option-terminator'。
  • index <number> 包含该 token 的 args 中元素的索引。因此，token 的来源参数是 args[token.index]。
• 选项令牌
  • name <string> 选项的完整名称。
  • rawName <string> 如何在参数中使用选项，比如 --foo 的 -f。
  • value <string> | <undefined> 在参数中指定的选项值。 布尔选项未定义。
  • inlineValue <boolean> | <undefined> 是否在行内指定选项值，例如 --foo=bar。
• 位置标记
  • value <string> args 中位置参数的值（即 args[index]）。
• 选项终止符标记

返回的标记按输入参数中出现的顺序排列。在参数中出现多次的选项会为每次出现生成一个标记。像 -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>

给出一个示例 .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>

接受一个遵循常见错误优先回调风格的函数，即将 (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.】

import { promisify } from 'node:util';
import { stat } from 'node:fs';

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

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

或者，等效地使用 async function：

【Or, equivalently using async functions:】

import { promisify } from 'node:util';
import { stat } from 'node:fs';

const promisifiedStat = promisify(stat);

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

callStat();const { promisify } = require('node:util');
const { stat } = require('node:fs');

const promisifiedStat = promisify(stat);

async function callStat() {
  const stats = await promisifiedStat('.');
  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 是函数，但它的最后一个参数不是以错误优先的回调函数，它仍然会被传入一个以错误为优先的回调函数作为最后一个参数。

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

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

import { promisify } from 'node:util';

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

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

const foo = new Foo();

const naiveBar = promisify(foo.bar);
// TypeError: Cannot read properties of undefined (reading 'a')
// 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'const { promisify } = require('node:util');

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

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

const foo = new Foo();

const naiveBar = promisify(foo.bar);
// TypeError: Cannot read properties of undefined (reading 'a')
// 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():】

import { promisify } from 'node:util';

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

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

const promisified = promisify(doSomething);
console.log(promisified === doSomething[promisify.custom]);
// prints 'true'const { promisify } = require('node:util');

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

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

const promisified = promisify(doSomething);
console.log(promisified === doSomething[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>，可用于声明自定义函数的 Promise 版本，参见 自定义 promise 化函数。

除了可以通过 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>

返回移除所有 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 中定义的文本格式数组。
• text <string> 要格式化的文本。
• options <Object>
  • validateStream <boolean> 如果为 true，将检查 stream 是否可以处理颜色。默认值： true。
  • stream <Stream> 一个将被验证是否可以着色的流。默认值： process.stdout。

此函数会根据传入的 format 返回格式化文本，以便在终端中打印。它会根据终端的功能进行处理，并根据 NO_COLOR、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_COLOR, 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(errorMessage);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(errorMessage);拷贝

util.inspect.colors 还提供文本格式，如 italic（斜体）和 underline（下划线），并且你可以将两者结合使用：

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
); 拷贝

特殊格式值 none 不会对文本应用任何额外样式。

【The special format value none applies no additional styling to the text.】

完整的格式列表可以在 修饰符 中找到。

【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)】

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

【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'。
• options <Object>
  • fatal <boolean> 如果解码失败是否致命。 当禁用 ICU 时不支持此选项（参见 国际化）。 默认值： false。
  • ignoreBOM <boolean> 当为 true 时，TextDecoder 会在解码结果中包含字节顺序标记。 当为 false 时，字节顺序标记将从输出中移除。此选项仅在 encoding 为 'utf-8'、'utf-16be' 或 'utf-16le' 时使用。默认值: 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 实例，包含编码的数据。
• options <Object>
  • stream <boolean> 如果预期有更多的数据块，则为 true。 默认值: false。
• 返回：<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> 要编码的文本。**默认值：**空字符串。
• 返回：<Uint8Array>

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

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

textEncoder.encodeInto(src, dest)#>

• src <string> 要编码的文本。
• dest <Uint8Array> 用于存放编码结果的数组。
• 返回：<Object>
  • read <number> src 的已读取 Unicode 代码单元。
  • written <number> dest 的 UTF-8 字节数。

UTF-8 会将 src 字符串编码到 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 后的字符串。

【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>

将给定的 <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> 任何与可中止操作相关联并被弱引用的非空对象。如果在 signal 中止之前 resource 被垃圾回收，Promise 会保持挂起状态，从而允许 Node.js 停止跟踪它。这有助于防止在长时间运行或不可取消的操作中发生内存泄漏。
• 返回：<Promise>

监听提供的 signal 上的中止事件，并返回在 signal 被中止时解析的 Promise。如果提供了 resource，它会对操作关联的对象进行弱引用，因此如果在 signal 中止之前 resource 被垃圾回收，则返回的 Promise 将保持挂起状态。这可以防止长时间运行或不可取消操作中的内存泄漏。

【Listens to abort event on the provided signal and returns a promise that resolves when the signal is aborted. If resource is provided, it weakly references the operation's associated object, so if resource is garbage collected before the signal aborts, then returned promise shall remain pending. This prevents memory leaks in long-running or non-cancelable operations.】

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

// Obtain an object with an abortable signal, like a custom resource or operation.
const dependent = obtainSomethingAbortable();

// Pass `dependent` as the resource, indicating the promise should only resolve
// if `dependent` is still in memory when the signal is aborted.
aborted(dependent.signal, dependent).then(() => {

  // This code runs when `dependent` is aborted.
  console.log('Dependent resource was aborted.');
});

// Simulate an event that triggers the abort.
dependent.on('event', () => {
  dependent.abort(); // This will cause the `aborted` promise to resolve.
});import { aborted } from 'node:util';

// Obtain an object with an abortable signal, like a custom resource or operation.
const dependent = obtainSomethingAbortable();

// Pass `dependent` as the resource, indicating the promise should only resolve
// if `dependent` is still in memory when the signal is aborted.
aborted(dependent.signal, dependent).then(() => {

  // This code runs when `dependent` is aborted.
  console.log('Dependent resource was aborted.');
});

// Simulate an event that triggers the abort.
dependent.on('event', () => {
  dependent.abort(); // This will cause the `aborted` promise to resolve.
});拷贝

util.types#>

util.types 提供了对不同类型内置对象的类型检查。与 instanceof 或 Object.prototype.toString.call(value) 不同，这些检查不会检查从 JavaScript 可访问的对象属性（例如它们的原型），并且通常具有调用 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.】

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

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

util.types.isAnyArrayBuffer(value)#>

• value <any>
• 返回：<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>

如果该值是某个 <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>

如果值是 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>

如果值是内置的 <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>

如果值是 异步函数，则返回 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>

如果值是 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.isBigIntObject(value)#>

• value <any>
• 返回：<boolean>

如果值是 BigInt 对象（例如由 Object(BigInt(123)) 创建），则返回 true。

【Returns true if the value is a BigInt object, e.g. created by Object(BigInt(123)).】

util.types.isBigIntObject(Object(BigInt(123)));   // Returns true
util.types.isBigIntObject(BigInt(123));   // Returns false
util.types.isBigIntObject(123);  // Returns false 拷贝

util.types.isBigUint64Array(value)#>

• value <any>
• 返回：<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>

如果值是布尔对象，例如由 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>

如果值是任何封装的原始对象，例如通过 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>

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

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

util.types.isDataView(value)#>

• value <any>
• 返回：<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>

如果值是内置的 <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>

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

【Returns true if the value is a native External value.】

本地 External 值是一种特殊类型的对象，它包含一个用于本地代码访问的原始 C++ 指针（void*），并且没有其他属性。这类对象要么由 Node.js 内部创建，要么由本地插件创建。在 JavaScript 中，它们是具有 null 原型的 冷冻 对象。

【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)
... 拷贝

import native from 'napi_addon.node';
import { types } from 'node:util';

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

const data = native.myNapi();
types.isExternal(data); // returns true
types.isExternal(0); // returns false
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.isFloat16Array(value)#>

• value <any>
• 返回：<boolean>

如果值是内置的 Float16Array 实例，则返回 true。

【Returns true if the value is a built-in Float16Array instance.】

util.types.isFloat16Array(new ArrayBuffer());  // Returns false
util.types.isFloat16Array(new Float16Array());  // Returns true
util.types.isFloat16Array(new Float32Array());  // Returns false 拷贝

util.types.isFloat32Array(value)#>

• value <any>
• 返回：<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>

如果值是内置的 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>

如果该值是生成器函数，则返回 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>

如果值是由内置生成器函数返回的生成器对象，则返回 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>

如果值是内置的 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>

如果值是内置的 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>

如果值是内置的 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>

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

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

util.types.isMap(value)#>

• value <any>
• 返回：<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>

如果该值是从内置 <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>

如果该值是 模块命名空间对象 的实例，则返回 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>

如果该值是由 内置 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() 对来自不同 字段 的错误返回 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:】

import { createContext, runInContext } from 'node:vm';
import { types } from 'node:util';

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

const context = createContext({});
const myError = runInContext('new Error()', context);
console.log(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>

如果值是数字对象（例如通过 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>

如果该值是内置的 <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>

如果值是 <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>

如果该值是正则表达式对象，则返回 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>

如果值是内置的 <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>

如果该值是从内置 <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>

如果值是内置的 <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>

如果值是字符串对象（例如通过 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>

如果值是符号对象（通过对 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>

如果值是内置的 <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>

如果值是内置的 <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>

如果值是内置的 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>

如果值是内置的 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>

如果值是内置的 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>

如果值是内置的 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>

如果值是内置的 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>

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>

如果给定的 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)#>

• object <any>
• 返回：<boolean>

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

【Returns true if the given object is a Buffer. Otherwise, returns false.】

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

util.isBuffer({ length: 0 });
// Returns: false
util.isBuffer([]);
// Returns: false
util.isBuffer(Buffer.from('hello world'));
// Returns: true 拷贝

util.isDate(object)#>

• object <any>
• 返回：<boolean>

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

【Returns true if the given object is a Date. Otherwise, returns false.】

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

util.isDate(new Date());
// Returns: true
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({});
// Returns: false 拷贝

util.isError(object)#>