Node.js v18.18.2 文档

util.callbackify(original)#

• original <函数> 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#

• <布尔值>

util.debuglog().enabled getter用于创建可在基于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 <Function>已弃用的函数。
• msg <string>调用已弃用的函数时显示的警告消息。
• code <string>弃用代码。有关代码列表，请参阅已弃用的 API 列表。
• 返回：<Function>已弃用的函数被包装以发出警告。

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，则会出现警告和堆栈第一次调用已弃用的函数时，trace 会打印到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 函数的对象将使用带有 选项{ 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 对象格式的对象的字符串表示形式。类似于带有选项 { showHidden: true, showProxy: true }的util.inspect()。这将显示完整的对象，包括不可枚举的属性和代理。
• %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 <对象>
• format <字符串>

此函数与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 <数字>
• 返回：<字符串>

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

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

util.getSystemErrorMap()#

• 返回：<地图>

返回 Node.js API 中可用的所有系统错误代码的映射。错误代码和错误名称之间的映射取决于平台。有关常见错误的名称，请参阅常见系统错误。

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 <函数>
• superConstructor <函数>

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

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

这主要在Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)之上添加一些输入验证 。为了进一步方便起见，可以通过constructor.super_属性访问superConstructor 。

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 <对象>
  • 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、WeakMap和WeakSet元素的最大数量格式化时。设置为null或Infinity以显示所有元素。设置为0或负数以不显示任何元素。默认值： 100。
  • maxStringLength <整数>指定格式化时要包含的最大字符数。设置为null或Infinity以显示所有元素。设置为0或负数以不显示字符。默认值： 10000。
  • breakLength <integer>输入值拆分为多行的长度。设置为Infinity将输入格式设置为单行（与设置为true或任意数字 >= 1 的 compact结合） 。 默认值： 80。
  • compact <布尔值> | <integer>将其设置为false会导致每个对象键显示在新行上。它将在长度超过breakLength的文本中换行。如果设置为数字，则只要所有属性都适合 breakLength ，最多的 n内部元素就会统一在一行上。短数组元素也被分组在一起。有关更多信息，请参阅下面的示例。默认值： 3。
  • sorted <布尔值> | <Function>如果设置为true或函数，则对象的所有属性以及Set和Map条目都会在结果字符串中排序。如果设置为true，则使用默认排序。如果设置为函数，则将其用作比较函数。
  • getters <布尔值> | <string>如果设置为true，则检查 getter。如果设置为'get'，则仅检查没有相应 setter 的 getter。如果设置为'set'，则仅检查具有相应 setter 的 getter。这可能会导致副作用，具体取决于 getter 函数。 默认值： false。
  • numericSeparator <boolean>如果设置为true，则使用下划线分隔所有 bigint 和数字中的每三位数字。 默认值： 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(thousand, million, bigNumber, bigDecimal);
// 1_000 1_000_000 123_456_789n 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 - 将所有（颜色）修饰符重置为默认值
• 粗体- 使文本加粗
• italic - 使文本斜体
• underline - 使文本带有下划线
• 删除线- 在文本中心放置一条水平线（别名：strikeThrough、crossedout、crossedOut）
• hidden - 打印文本，但使其不可见（别名：隐藏）
• 暗淡- 颜色强度降低（别名： faint）
• overlined - 使文本带有上划线
• 闪烁 - 以一定间隔隐藏和显示文本
• inverse - 交换前景色和背景色（别名：swapcolors、swapColors）
• doubleunderline - 使文本加双下划线（别名：doubleUnderline）
• 框架- 在文本周围绘制框架

前景色#

• 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 <任意>
• val2 <任意>
• 返回：<布尔值>

如果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#

• <字符串>

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

• <字符串>

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

• <字符串>

掌握 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#

• <MIME参数>

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

mime.toString()#

• 返回：<字符串>

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

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

mime.toJSON()#

• 返回：<字符串>

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 <字符串>

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

mimeParams.entries()#

• 返回：<迭代器>

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

mimeParams.get(name)#

• name <字符串>
• 返回：<string>或null如果不存在具有给定 name的名称-值对。

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

mimeParams.has(name)#

• name <字符串>
• 返回：<布尔值>

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

mimeParams.keys()#

• 返回：<迭代器>

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

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 <字符串>
• value <字符串>

将与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()#

• 返回：<迭代器>

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

mimeParams[@@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 <字符串> | <布尔值> | <字符串[]> | <boolean[]>未通过 args 设置时的默认选项值。它必须与type属性具有相同的类型 。当multiple为true时，它必须是一个数组。
  • strict <boolean>当遇到未知参数或传递的参数与type中配置的type不匹配时是否应该抛出错误 。 默认值： true。
  • allowPositionals <boolean>此命令是否接受位置参数。 默认值： 如果strict是true，则为 false ，否则为true。
  • tokens <boolean>返回解析后的标记。这对于扩展内置行为非常有用，从添加额外的检查到以不同的方式重新处理令牌。 默认值： false。

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

  • values <Object>已解析选项名称与其<string> 或<boolean>值的映射。
  • positionals <string[]>位置参数。
  • tokens <对象[]> | <未定义>请参阅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

util.parseArgs是实验性的，行为可能会改变。加入pkgjs/parseargs中的对话，为设计做出贡献。

parseArgs tokens#

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

• 所有代币
  • kind <string> “选项”、“位置”或“选项终止符”之一。
  • index <number>包含标记的args中元素的索引。因此令牌的源参数是args[token.index]。
• 期权代币
  • name <string>选项的长名称。
  • rawName <string>如何在参数中使用选项，例如--foo的-f。
  • value <字符串> | <未定义> args 中指定的选项值。布尔选项未定义。
  • inlineValue <布尔值> | <undefined>选项值是否指定为内联，例如--foo=bar。
• 位置标记
  • value <string> args 中位置参数的值（即args[index]）。
• 选项终止符标记

返回的标记按照输入参数中遇到的顺序排列。在 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.promisify(original)#

• original <函数>
• 返回：<函数>

采用遵循常见错误优先回调风格的函数，即采用(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 s：

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

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

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>可用于声明函数的自定义 Promisified 变体，请参阅自定义 Promisified 函数。

除了可以通过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 <字符串>
• 返回：<字符串>

返回str，并删除所有 ANSI 转义码。

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
// Prints "value" 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 数据）#

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

禁用 ICU 时支持的编码#

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

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

• encoding <string>标识此TextDecoder实例支持的encoding。默认值： 'utf-8'。
• options <对象>
  • 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> | <数据视图> | <TypedArray>包含编码数据的ArrayBuffer、DataView或 TypedArray实例。
• options <对象>
  • stream <boolean> true如果需要额外的数据块。 默认值： false。
• 返回：<字符串>

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

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

textDecoder.encoding#

• <字符串>

TextDecoder实例支持的编码。

textDecoder.fatal#

• <布尔值>

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

textDecoder.ignoreBOM#

• <布尔值>

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

类：util.TextEncoder#

WHATWG 编码标准 TextEncoder API的实现。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>保存编码结果的数组。
• 返回：<对象>
  • read <number> src 读取的 Unicode 代码单元。
  • written <number> dest 写入的 UTF-8 字节。

UTF-8 将src字符串编码为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#

• <字符串>

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

util.toUSVString(string)#

• string <字符串>

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

util.transferableAbortController()#

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

util.transferableAbortSignal(signal)#

• signal <中止信号>
• 返回：<中止信号>

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

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

util.aborted(signal, resource)#

• signal <中止信号>
• resource <Object>任何非空实体，对其的引用是弱保留的。
• 返回：< Promise >

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

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 中进行类型检查的插件开发人员有用。

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

util.types.isAnyArrayBuffer(value)#

• value <任意>
• 返回：<布尔值>

如果该值是内置的 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 <任意>
• 返回：<布尔值>

如果值是 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 <任意>
• 返回：<布尔值>

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

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

util.types.isArrayBuffer(value)#

• value <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

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

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

util.types.isBigInt64Array(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isBigUint64Array(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isBooleanObject(value)#

• value <任意>
• 返回：<布尔值>

如果值是布尔对象（例如由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 <任意>
• 返回：<布尔值>

如果该值是任何装箱原始对象，例如由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 <对象>
• 返回：<布尔值>

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

util.types.isDataView(value)#

• value <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

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

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

util.types.isExternal(value)#

• value <任意>
• 返回：<布尔值>

如果该值是本机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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

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

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

util.types.isGeneratorObject(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isInt8Array(value)#

• value <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <对象>
• 返回：<布尔值>

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

util.types.isMap(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isMapIterator(value)#

• value <任意>
• 返回：<布尔值>

如果该值是为内置 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 <任意>
• 返回：<布尔值>

如果该值是Module Namespace Object的实例，则返回true。

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

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

util.types.isNativeError(value)#

• value <任意>
• 返回：<布尔值>

如果值是由内置 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 <任意>
• 返回：<布尔值>

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

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

util.types.isPromise(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isProxy(value)#

• value <任意>
• 返回：<布尔值>

如果值是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 <任意>
• 返回：<布尔值>

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

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

util.types.isSet(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isSetIterator(value)#

• value <任意>
• 返回：<布尔值>

如果该值是为内置 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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

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

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

util.types.isSymbolObject(value)#

• value <任意>
• 返回：<布尔值>

如果该值是通过对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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

如果该值是内置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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

如果该值是内置的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 <任意>
• 返回：<布尔值>

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

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

util.types.isWeakSet(value)#

• value <任意>
• 返回：<布尔值>

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

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

util.types.isWebAssemblyCompiledModule(value)#

• value <任意>
• 返回：<布尔值>

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

const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module);  // Returns true copy

已弃用的 API#

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

util._extend(target, source)#

• target <对象>
• source <对象>

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

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

util.isArray(object)#

• object <任意>
• 返回：<布尔值>

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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <任意>
• 返回：<布尔值>

如果给定的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 <字符串>

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

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

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