Node.js v21.7.2 文档

util.callbackify(original)#

• original <Function> 一个 async 函数
• 返回：<Function> 一个回调风格的函数

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

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);
}); copy

将打印

hello world copy

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

由于 null 对回调的第一个参数具有特殊含义，如果包装的函数以虚假值为原因拒绝 Promise，则该值将包装在一个 Error 中，原始值存储在一个名为 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
}); copy

util.debuglog(section[, callback])#

• section <string> 用于标识创建 debuglog 函数的应用程序部分的字符串。
• callback <Function> 第一次调用日志记录函数时，如果函数参数是一个更优化的日志记录函数，则会调用此回调函数。
• 返回值: <Function> 日志记录函数

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

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

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

如果此程序在环境中使用 NODE_DEBUG=foo 运行，则它将输出类似于以下内容的内容

FOO 3245: hello from foo [123] copy

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

section 也支持通配符

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

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

如果它在环境中使用 NODE_DEBUG=foo* 运行，则它将输出类似于以下内容的内容

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

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

可选的 callback 参数可用于将日志记录函数替换为不同的函数，该函数没有初始化或不必要的包装。

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;
}); copy

debuglog().enabled#

• <boolean>

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

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

如果此程序在环境中使用 NODE_DEBUG=foo 运行，则它将输出类似于以下内容的内容

hello from foo [123] copy

util.debug(section)#

util.debuglog 的别名。使用该别名可以提高可读性，因为在仅使用 util.debuglog().enabled 时，它不会暗示日志记录。

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

• fn <函数> 被弃用的函数。
• msg <字符串> 当调用弃用函数时显示的警告消息。
• code <字符串> 弃用代码。有关代码列表，请参阅 弃用 API 列表。
• 返回值：<函数> 用于发出警告的包装弃用函数。

util.deprecate() 方法以这样一种方式包装 fn（它可以是函数或类），使其被标记为已弃用。

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

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

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

如果在对 util.deprecate() 的多次调用中提供了相同的可选 code，则警告将仅针对该 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 copy

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

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

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

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

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

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

util.format() 方法使用第一个参数作为类似 printf 的格式字符串返回格式化的字符串，该字符串可以包含零个或多个格式规范。每个规范都用来自相应参数的转换值替换。

• %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> 格式化的字符串

如果规范没有相应的参数，则不会被替换

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

如果值的类型不是 string，则使用 util.inspect() 格式化不是格式字符串的一部分的值。

如果传递给util.format()方法的参数数量超过了格式说明符的数量，则多余的参数将被连接到返回的字符串中，并用空格分隔。

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

如果第一个参数不包含有效的格式说明符，则util.format()将返回一个字符串，该字符串是所有参数的连接，并用空格分隔。

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

如果只传递一个参数给util.format()，则它将按原样返回，没有任何格式化。

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

util.format()是一个同步方法，旨在用作调试工具。某些输入值可能会产生显著的性能开销，从而阻塞事件循环。请谨慎使用此函数，并且不要在热代码路径中使用它。

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

• inspectOptions <Object>
• format <string>

此函数与util.format()相同，只是它接受一个inspectOptions参数，该参数指定传递给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. copy

util.getSystemErrorName(err)#

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

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

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

util.getSystemErrorMap()#

• 返回：<Map>

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

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

util.inherits(constructor, superConstructor)#

• constructor <Function>
• superConstructor <Function>

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

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

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

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!" copy

使用 class 和 extends 的 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'); copy

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 为被检查的值创建一个可识别的标签。

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] {}' copy

循环引用通过使用引用索引指向它们的锚点。

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] }
// } copy

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

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

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

以下示例突出显示 compact 选项的效果。

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

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

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 } } copy

sorted 选项确保对象的属性插入顺序不会影响 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 }),
); copy

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

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

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

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

util.inspect() 是一个同步方法，用于调试。它的最大输出长度约为 128 MiB。导致更长输出的输入将被截断。

自定义 util.inspect 颜色#

util.inspect 的彩色输出（如果启用）可以通过 util.inspect.styles 和 util.inspect.colors 属性在全局范围内自定义。

util.inspect.styles 是一个映射，将样式名称与 util.inspect.colors 中的颜色相关联。

默认样式和关联的颜色如下：

• 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().

预定义的控制代码列在下面（按“修饰符”、“前景色”和“背景色”分组）。

修饰符#

修饰符支持在不同的终端中有所不同。如果不受支持，它们大多会被忽略。

• reset - 将所有（颜色）修饰符重置为默认值
• bold - 使文本加粗
• italic - 使文本斜体
• underline - 使文本带下划线
• strikethrough - 在文本中心添加一条水平线（别名：strikeThrough, crossedout, crossedOut）
• hidden - 打印文本，但使其不可见（别名：conceal）
• dim - 降低颜色强度（别名：faint）
• overlined - 使文本带横线
• blink - 以一定间隔隐藏和显示文本
• inverse - 交换前景和背景颜色（别名：swapcolors, swapColors）
• doubleunderline - 使文本带双下划线（别名：doubleUnderline）
• framed - 在文本周围绘制一个框架

前景色#

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• gray (别名：grey, blackBright)
• redBright
• greenBright
• yellowBright
• blueBright
• magentaBright
• cyanBright
• whiteBright

背景色#

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite
• bgGray (别名：bgGrey, bgBlackBright)
• bgRedBright
• bgGreenBright
• bgYellowBright
• bgBlueBright
• bgMagentaBright
• bgCyanBright
• bgWhiteBright

对象上的自定义检查函数#

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

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 >" copy

自定义的 [util.inspect.custom](depth, opts, inspect) 函数通常返回一个字符串，但也可以返回任何类型的返回值，这些返回值将由 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' }" copy

util.inspect.custom#

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

除了可以通过 util.inspect.custom 访问之外，此符号还 在全局范围内注册，可以在任何环境中以 Symbol.for('nodejs.util.inspect.custom') 的方式访问。

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

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

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

util.inspect.defaultOptions#

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

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 copy

util.isDeepStrictEqual(val1, val2)#

• val1 <any>
• val2 <any>
• 返回值：<boolean>

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

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

类：util.MIMEType#

MIMEType 类 的实现。

根据浏览器惯例，MIMEType 对象的所有属性都作为类原型上的 getter 和 setter 实现，而不是作为对象本身上的数据属性。

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

构造函数：new MIMEType(input)#

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

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

import { MIMEType } from 'node:util';

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

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

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

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/plaincopy

mime.type#

• <string>

获取和设置 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/javascriptcopy

mime.subtype#

• <string>

获取和设置 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/javascriptcopy

mime.essence#

• <string>

获取 MIME 的本质。此属性为只读。使用 mime.type 或 mime.subtype 来更改 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=valuecopy

mime.params#

• <MIMEParams>

获取表示 MIME 参数的 MIMEParams 对象。此属性为只读。有关详细信息，请参见 MIMEParams 文档。

mime.toString()#

• 返回：<string>

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

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

mime.toJSON()#

• 返回：<string>

是 mime.toString() 的别名。

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

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"]copy

类: util.MIMEParams#

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

构造函数: new MIMEParams()#

创建一个新的 MIMEParams 对象，其中包含空参数。

import { MIMEParams } from 'node:util';

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

const myParams = new MIMEParams();copy

mimeParams.delete(name)#

• name <string>

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

mimeParams.entries()#

• 返回: <Iterator>

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

mimeParams.get(name)#

• name <string>
• 返回: <string> | <null> 如果没有名称为 name 的名称-值对，则返回字符串或 null。

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

mimeParams.has(name)#

• name <string>
• 返回值：<boolean>

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

mimeParams.keys()#

• 返回: <Iterator>

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

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
//   barcopy

mimeParams.set(name, value)#

• name <string>
• value <string>

将与name关联的MIMEParams对象中的值设置为value。如果存在任何名称为name的现有键值对，则将第一个此类对的值设置为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=xyzcopy

mimeParams.values()#

• 返回: <Iterator>

返回每个键值对值的迭代器。

mimeParams[@@iterator]()#

• 返回: <Iterator>

是 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 bazcopy

util.parseArgs([config])#

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

  • args <string[]> 参数字符串数组。默认值：process.argv，移除execPath 和 filename。
  • 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 标记 部分。仅当 config 包含 tokens: true 时返回。

提供比直接与 process.argv 交互更高级的命令行参数解析 API。它接受预期参数的规范，并返回一个包含解析后的选项和位置参数的结构化对象。

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' } []copy

parseArgs tokens#

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

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

返回的标记按输入 args 中遇到的顺序排列。在 args 中多次出现的选项会为每次使用生成一个标记。短选项组（如 -xy）会扩展为每个选项的标记。因此，-xxx 会生成三个标记。

例如，为了使用返回的标记来添加对否定选项（如 --no-color）的支持，可以重新处理这些标记以更改为否定选项存储的值。

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 });copy

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

$ 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 } copy

util.parseEnv(content)#

• content <string>

.env 文件的原始内容。

• 返回：<Object>

给定一个示例 .env 文件

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' }copy

util.promisify(original)#

• original <Function>
• 返回值：<Function>

接受一个遵循常见错误优先回调风格的函数，即以 (err, value) => ... 回调作为最后一个参数，并返回一个返回 Promise 的版本。

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.
}); copy

或者，等效地使用 async function

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

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

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

callStat(); copy

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

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

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

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' copy

自定义 Promise 化函数#

使用 util.promisify.custom 符号，可以覆盖 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' copy

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

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

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

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

util.promisify.custom#

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

除了可以通过 util.promisify.custom 访问之外，此符号还 在全局注册，可以在任何环境中以 Symbol.for('nodejs.util.promisify.custom') 访问。

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

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

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

util.stripVTControlCharacters(str)#

• str <string>
• 返回：<string>

返回删除所有 ANSI 转义码后的 str。

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

util.styleText(format, text)#

• format <string> 在 util.inspect.colors 中定义的文本格式。
• text <string> 要格式化的文本。

此函数根据传递的 format 返回格式化的文本。

import { styleText } from 'node:util';
const errorMessage = styleText('red', 'Error! Error!');
console.log(errorMessage);const { styleText } = require('node:util');
const errorMessage = styleText('red', 'Error! Error!');
console.log(errorMessage);copy

util.inspect.colors 还提供文本格式，例如 italic 和 underline，您可以将两者结合使用

console.log(
  util.styleText('underline', util.styleText('italic', 'My italic underlined message')),
); copy

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

类：util.TextDecoder#

对 WHATWG 编码标准 TextDecoder API 的实现。

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

WHATWG 支持的编码#

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

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

默认支持的编码（使用完整的 ICU 数据）#

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

禁用 ICU 时支持的编码#

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

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

• encoding <string> 标识此 TextDecoder 实例支持的 encoding。默认值： 'utf-8'。
• options <Object>
  • fatal <boolean> 如果解码失败是致命的，则为 true。禁用 ICU 时不支持此选项（请参阅 国际化）。默认值： false。
  • ignoreBOM <boolean> 当 true 时，TextDecoder 将在解码结果中包含字节顺序标记。当 false 时，字节顺序标记将从输出中删除。此选项仅在 encoding 为 'utf-8'、'utf-16be' 或 'utf-16le' 时使用。默认值： false。

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

TextDecoder 类也存在于全局对象上。

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() 后发出。

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

textDecoder.encoding#

• <string>

TextDecoder 实例支持的编码。

textDecoder.fatal#

• <boolean>

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

textDecoder.ignoreBOM#

• <boolean>

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

类：util.TextEncoder#

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

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

TextEncoder 类也存在于全局对象上。

textEncoder.encode([input])#

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

使用 UTF-8 编码 input 字符串，并返回包含编码字节的 Uint8Array。

textEncoder.encodeInto(src, dest)#

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

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

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

textEncoder.encoding#

• <string>

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

util.toUSVString(string)#

• string <string>

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

util.transferableAbortController()#

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

util.transferableAbortSignal(signal)#

• signal <AbortSignal>
• 返回：<AbortSignal>

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

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

util.aborted(signal, resource)#

• signal <AbortSignal>
• resource <Object> 任何非空实体，对其的引用被弱持有。
• 返回：<Promise>

监听提供的 signal 上的 abort 事件，并返回一个 promise，该 promise 在 signal 被中止时被 fulfilled。如果传递的 resource 在 signal 被中止之前被垃圾回收，则返回的 promise 将无限期地保持 pending 状态。

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

const dependent = obtainSomethingAbortable();

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

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

const dependent = obtainSomethingAbortable();

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

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

util.types#

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

结果通常不会对值在 JavaScript 中公开的属性或行为类型做出任何保证。它们主要对希望在 JavaScript 中进行类型检查的附加组件开发人员有用。

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

util.types.isAnyArrayBuffer(value)#

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

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

另请参见 util.types.isArrayBuffer() 和 util.types.isSharedArrayBuffer().

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

util.types.isArrayBufferView(value)#

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

如果该值为 ArrayBuffer 视图（如类型化数组对象或 DataView）的实例，则返回 true。等效于 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 copy

util.types.isArgumentsObject(value)#

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

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

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

util.types.isArrayBuffer(value)#

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

如果值为内置 ArrayBuffer 实例，则返回 true。这不包括 SharedArrayBuffer 实例。通常，最好同时测试两者；有关详细信息，请参阅 util.types.isAnyArrayBuffer()。

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

util.types.isAsyncFunction(value)#

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

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

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

util.types.isBigInt64Array(value)#

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

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

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

util.types.isBigUint64Array(value)#

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

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

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

util.types.isBooleanObject(value)#

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

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

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 copy

util.types.isBoxedPrimitive(value)#

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

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

例如

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 copy

util.types.isCryptoKey(value)#

• value <Object>
• 返回值：<boolean>

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

util.types.isDataView(value)#

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

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

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

另请参见 ArrayBuffer.isView()。

util.types.isDate(value)#

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

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

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

util.types.isExternal(value)#

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

如果值是本机 External 值，则返回 true。

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

#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)
... copy

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 copy

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

util.types.isFloat32Array(value)#

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

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

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

util.types.isFloat64Array(value)#

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

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

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

util.types.isGeneratorFunction(value)#

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

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

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

util.types.isGeneratorObject(value)#

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

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

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

util.types.isInt8Array(value)#

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

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

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

util.types.isInt16Array(value)#

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

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

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

util.types.isInt32Array(value)#

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

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

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

util.types.isKeyObject(value)#

• value <Object>
• 返回值：<boolean>

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

util.types.isMap(value)#

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

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

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

util.types.isMapIterator(value)#

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

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

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 copy

util.types.isModuleNamespaceObject(value)#

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

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

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

util.types.isModuleNamespaceObject(ns);  // Returns true copy

util.types.isNativeError(value)#

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

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

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

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

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

一个值是原生错误类的 instanceof 与 isNativeError() 对该值返回 true 不等效。isNativeError() 对来自不同 领域 的错误返回 true，而 instanceof Error 对这些错误返回 false。

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

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

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

util.types.isNumberObject(value)#

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

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

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

util.types.isPromise(value)#

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

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

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

util.types.isProxy(value)#

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

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

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

util.types.isRegExp(value)#

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

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

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

util.types.isSet(value)#

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

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

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

util.types.isSetIterator(value)#

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

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

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 copy

util.types.isSharedArrayBuffer(value)#

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

如果该值为内置 SharedArrayBuffer 实例，则返回 true。这不包括 ArrayBuffer 实例。通常，最好同时测试两者；有关详细信息，请参阅 util.types.isAnyArrayBuffer()。

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

util.types.isStringObject(value)#

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

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

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

util.types.isSymbolObject(value)#

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

如果值是符号对象，通过对 Symbol 原语调用 Object() 创建，则返回 true。

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

util.types.isTypedArray(value)#

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

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

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

另请参见 ArrayBuffer.isView()。

util.types.isUint8Array(value)#

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

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

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

util.types.isUint8ClampedArray(value)#

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

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

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

util.types.isUint16Array(value)#

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

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

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

util.types.isUint32Array(value)#

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

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

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

util.types.isWeakMap(value)#

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

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

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

util.types.isWeakSet(value)#

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

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

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

已弃用 API#

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

util._extend(target, source)#

• target <Object>
• source <Object>

util._extend() 方法最初不打算在 Node.js 内部模块之外使用。 社区还是找到了它并使用了它。

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

util.isArray(object)#

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

Array.isArray() 的别名。

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

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

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

util.isBoolean(object)#

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

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

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

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

util.isBuffer(object)#

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

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

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

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

util.isDate(object)#

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

如果给定的 object 是一个 Date，则返回 true。否则，返回 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 copy

util.isError(object)#

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

如果给定的 object 是一个 Error，则返回 true。否则，返回 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 copy

此方法依赖于 Object.prototype.toString() 的行为。当 object 参数操作 @@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 copy

util.isFunction(object)#

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

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

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

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

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

util.isNull(object)#

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

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

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

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

util.isNullOrUndefined(object)#

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

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

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

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

util.isNumber(object)#

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

如果给定的 object 是一个 Number，则返回 true。否则，返回 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 copy

util.isObject(object)#

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

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

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

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

util.isPrimitive(object)#

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

如果给定的 object 是一个原始类型，则返回 true。否则，返回 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 copy

util.isRegExp(object)#

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

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

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

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

util.isString(object)#

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

如果给定的 object 是一个 string，则返回 true。否则，返回 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 copy

util.isSymbol(object)#

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

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

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

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

util.isUndefined(object)#

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

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

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

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

util.log(string)#

• string <string>

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

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

util.log('Timestamped message.'); copy