Node.js v16.20.2 文档

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.

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 函数的应用部分。
• 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.

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> 正在被弃用的函数。
• 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.

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 的格式字符串。

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 函数的对象将使用 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.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.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:

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、Set、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() 会使用构造函数的名称和/或 @@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(thousand, million, bigNumber, bigDecimal);
// 1_000 1_000_000 123_456_789n 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.

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> 可用于声明自定义检查函数。

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

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>

如果 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.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。
  • 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' } []拷贝

util.parseArgs 是实验性的，行为可能会发生变化。加入 pkgjs/解析参数 的讨论，为设计贡献你的意见。

parseArgs tokens#>

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

🌐 Detailed parse information is available for adding custom behaviours 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 的取反选项添加支持，可以重新处理这些标记以更改存储在取反选项中的值。

🌐 For example to use the returned tokens to add support for a negated option like --no-color, the 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.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.

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

如果存在 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:

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> 可用于声明函数的自定义 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.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.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.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)
... 拷贝

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>

如果值是内置的 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 is an instance of a built-in Error type.

util.types.isNativeError(new Error());  // Returns true
util.types.isNativeError(new TypeError());  // Returns true
util.types.isNativeError(new RangeError());  // Returns 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 拷贝

util.types.isWebAssemblyCompiledModule(value)#>

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

如果值是内置的 WebAssembly.Module 实例，则返回 true。

🌐 Returns true if the value is a built-in WebAssembly.Module instance.

const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module);  // 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)#>

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

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

🌐 Returns true if the given object is an Error. Otherwise, returns false.

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

util.isError(new Error());
// Returns: true
util.isError(new TypeError());
// Returns: true
util.isError({ name: 'Error', message: 'an error occurred' });
// Returns: false 拷贝

这种方法依赖于 Object.prototype.toString() 的行为。当 object 参数操作 @@toStringTag 时，有可能得到不正确的结果。

🌐 This method relies on Object.prototype.toString() behavior. It is possible to obtain an incorrect result when the object argument manipulates @@toStringTag.

const util = require('node:util');
const obj = { name: 'Error', message: 'an error occurred' };

util.isError(obj);
// Returns: false
obj[Symbol.toStringTag] = 'Error';
util.isError(obj);
// Returns: true 拷贝

util.isFunction(object)#>

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

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

🌐 Returns true if the given object is a Function. Otherwise, returns false.

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

function Foo() {}
const Bar = () => {};

util.isFunction({});
// Returns: false
util.isFunction(Foo);
// Returns: true
util.isFunction(Bar);
// Returns: true 拷贝

util.isNull(object)#>

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

如果给定的 object 严格为 null，则返回 true。否则，返回 false。

🌐 Returns true if the given object is strictly null. Otherwise, returns false.

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

util.isNull(0);
// Returns: false
util.isNull(undefined);
// Returns: false
util.isNull(null);
// Returns: true 拷贝

util.isNullOrUndefined(object)#>

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

如果给定的 object 为 null 或 undefined，则返回 true。否则，返回 false。

🌐 Returns true if the given object is null or undefined. Otherwise, returns false.

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

util.isNullOrUndefined(0);
// Returns: false
util.isNullOrUndefined(undefined);
// Returns: true
util.isNullOrUndefined(null);
// Returns: true 拷贝

util.isNumber(object)#>

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

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

🌐 Returns true if the given object is a Number. Otherwise, returns false.

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

util.isNumber(false);
// Returns: false
util.isNumber(Infinity);
// Returns: true
util.isNumber(0);
// Returns: true
util.isNumber(NaN);
// Returns: true 拷贝

util.isObject(object)#>

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

如果给定的 object 严格是一个 Object 且 不是 Function（尽管函数在 JavaScript 中也是对象），则返回 true。否则，返回 false。

🌐 Returns true if the given object is strictly an Object and not a Function (even though functions are objects in JavaScript). Otherwise, returns false.

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

util.isObject(5);
// Returns: false
util.isObject(null);
// Returns: false
util.isObject({});
// Returns: true
util.isObject(() => {});
// Returns: false 拷贝

util.isPrimitive(object)#>

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

如果给定的 object 是原始类型，则返回 true。否则，返回 false。

🌐 Returns true if the given object is a primitive type. Otherwise, returns false.

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

util.isPrimitive(5);
// Returns: true
util.isPrimitive('foo');
// Returns: true
util.isPrimitive(false);
// Returns: true
util.isPrimitive(null);
// Returns: true
util.isPrimitive(undefined);
// Returns: true
util.isPrimitive({});
// Returns: false
util.isPrimitive(() => {});
// Returns: false
util.isPrimitive(/^$/);
// Returns: false
util.isPrimitive(new Date());
// Returns: false 拷贝

util.isRegExp(object)#>

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

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

🌐 Returns true if the given object is a RegExp. Otherwise, returns false.

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

util.isRegExp(/some regexp/);
// Returns: true
util.isRegExp(new RegExp('another regexp'));
// Returns: true
util.isRegExp({});
// Returns: false 拷贝

util.isString(object)#>

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

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

🌐 Returns true if the given object is a string. Otherwise, returns false.

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

util.isString('');
// Returns: true
util.isString('foo');
// Returns: true
util.isString(String('foo'));
// Returns: true
util.isString(5);
// Returns: false 拷贝

util.isSymbol(object)#>

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

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

🌐 Returns true if the given object is a Symbol. Otherwise, returns false.

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

util.isSymbol(5);
// Returns: false
util.isSymbol('foo');
// Returns: false
util.isSymbol(Symbol('foo'));
// Returns: true 拷贝

util.isUndefined(object)#>

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

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

🌐 Returns true if the given object is undefined. Otherwise, returns false.

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

const foo = undefined;
util.isUndefined(5);
// Returns: false
util.isUndefined(foo);
// Returns: true
util.isUndefined(null);
// Returns: false 拷贝

util.log(string)#>

• string <string>

util.log() 方法将给定的 string 打印到 stdout，并附带时间戳。

🌐 The util.log() method prints the given string to stdout with an included timestamp.

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

util.log('Timestamped message.'); 拷贝