Node.js v26.0.0 文档

Util#

node:util 模块旨在满足 Node.js 内部 API 的需求。许多实用工具对于应用程序和模块开发者也同样有用。要访问它：

import util from 'node:util';
const util = require('node:util');
copy

util.callbackify(original)#

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

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

import { callbackify } from 'node:util';

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

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

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

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

将打印

hello world
copy

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

由于 null 作为回调的第一个参数具有特殊含义，如果封装的函数以虚值（falsy value）作为拒绝原因来拒绝 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.convertProcessSignalToExitCode(signal)#

• signal <string> 信号名称（例如 'SIGTERM'）
• 返回: <number> 对应于 signal 的退出代码

util.convertProcessSignalToExitCode() 方法将信号名称转换为其对应的 POSIX 退出代码。按照 POSIX 标准，由信号终止的进程的退出代码计算公式为 128 + 信号编号。

如果 signal 不是有效的信号名称，则会抛出错误。有关有效信号的列表，请参阅 signal(7)。

import { convertProcessSignalToExitCode } from 'node:util';

console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
const { convertProcessSignalToExitCode } = require('node:util');

console.log(convertProcessSignalToExitCode('SIGTERM')); // 143 (128 + 15)
console.log(convertProcessSignalToExitCode('SIGKILL')); // 137 (128 + 9)
copy

这在处理进程以根据终止进程的信号确定退出代码时特别有用。

util.debuglog(section[, callback])#

• section <string> 标识应用程序中正在创建 debuglog 函数部分的字符串。
• callback <Function> 回调函数，在日志记录函数第一次被调用时触发，参数为一个更优化的日志记录函数。
• 返回: <Function> 日志记录函数

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

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

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

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

如果程序在环境中以 NODE_DEBUG=foo 运行，则会输出类似以下内容

FOO 3245: hello from foo [123]
copy

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

section 也支持通配符

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

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

log('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 参数可用于将日志记录函数替换为不包含任何初始化或不必要包装的不同函数。

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

debuglog().enabled#

• 类型：<boolean>

util.debuglog().enabled getter 用于创建可根据 NODE_DEBUG 环境变量的存在进行条件判断的测试。如果 section 名称出现在该环境变量的值中，则返回值为 true。如果不是，则返回值为 false。

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

如果程序在环境中以 NODE_DEBUG=foo 运行，则会输出类似以下内容

hello from foo [123]
copy

util.debug(section)#

util.debuglog 的别名。使用此别名可以提高可读性，当仅使用 util.debuglog().enabled 时，它不会暗示正在进行日志记录。

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

• fn <Function> 被弃用的函数。
• msg <string> 调用已弃用函数时显示的警告消息。
• code <string> 弃用代码。请参阅 已弃用的 API 列表 以获取代码列表。
• options <Object>
• modifyPrototype <boolean> 当为 false 时，在发出弃用警告时不更改对象的原型。默认值: true。

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

import { deprecate } from 'node:util';

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

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

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

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

import { deprecate } from 'node:util';

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

const fn1 = deprecate(
  function() {
    return 'a value';
  },
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  function() {
    return 'a  different value';
  },
  'other dep message',
  'DEP0001',
);
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code
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.diff(actual, expected)#

• actual <Array> | <string> 要比较的第一个值

• expected <Array> | <string> 要比较的第二个值

• 返回: <Array> 差异条目数组。每个条目是一个包含两个元素的数组

  • 0 <number> 操作代码：-1 表示删除，0 表示无操作/未更改，1 表示插入
  • 1 <string> 与操作相关联的值

• 算法复杂度：O(N*D)，其中

• N 是两个序列的总长度之和 (N = actual.length + expected.length)

• D 是编辑距离（将一个序列转换为另一个序列所需的最小操作数）。

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

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

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

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

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

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

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

• %s：用于转换所有值（除了 BigInt、Object 和 -0）。BigInt 值将以 n 表示，没有用户定义的 toString 函数或 Symbol.toPrimitive 函数的对象将使用 util.inspect() 进行检查，选项为 { depth: 0, colors: false, compact: 3 }。
• %d：用于转换所有值（除了 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.getCallSites([frameCount][, options])#

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

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

与访问 error.stack 不同，此 API 返回的结果不受 Error.prepareStackTrace 的干扰。

import { getCallSites } from 'node:util';

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

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

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

  // ...
}

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

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

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

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

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

  // ...
}

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

anotherFunction();
copy

可以通过将 sourceMap 选项设置为 true 来重建原始位置。如果 source map 不可用，原始位置将与当前位置相同。当启用 --enable-source-maps 标志时，sourceMap 默认为 true。

import { getCallSites } from 'node:util';

interface Foo {
  foo: string;
}

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

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

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

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

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

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

// Without sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26
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 可用的所有系统错误代码的映射。错误代码和错误名称之间的映射是与平台相关的。有关常见错误名称，请参阅 常见系统错误。

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

util.getSystemErrorMessage(err)#

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

返回 Node.js API 中数字错误代码对应的字符串消息。错误代码和字符串消息之间的映射是与平台相关的。

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

util.setTraceSigInt(enable)#

• enable <boolean>

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

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 示例

import EventEmitter from 'node:events';

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

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6');
const EventEmitter = require('node:events');

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

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6');
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>、<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，下划线将用于分隔所有 bigint 和数字中每三位数字。默认值: false。

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

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

import { inspect } from 'node:util';

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

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }
const { inspect } = require('node:util');

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

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

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

import util from 'node:util';

console.log(util.inspect(util, { showHidden: true, depth: null }));
const util = require('node:util');

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

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

import { inspect } from 'node:util';

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

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

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

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

// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.
const { inspect } = require('node:util');

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

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

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

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

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

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

import { inspect } from 'node:util';

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

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } }
const { inspect } = require('node:util');

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

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

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

import { inspect } from 'node:util';
import assert from 'node:assert';

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

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

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

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

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

import { inspect } from 'node:util';

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

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45
const { inspect } = require('node:util');

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

console.log(inspect(thousand, { numericSeparator: true }));
// 1_000
console.log(inspect(million, { numericSeparator: true }));
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }));
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }));
// 1_234.123_45
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: 一种为字符类、组、断言和其他部分着色的方法，以提高可读性。要自定义着色，请更改 colors 属性。它默认为 ['red', 'green', 'yellow', 'cyan', 'magenta']，可以根据需要进行调整。该数组根据“深度”重复迭代。
• special: cyan (例如，Proxies)
• string: green
• symbol: green
• undefined: grey

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

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

复杂的自定义着色#

可以将一个方法定义为样式。它接收输入值的字符串化表示。如果启用了颜色且检查了该类型，则会调用它。

示例: util.inspect.styles.regexp(value)

• value <string> 输入类型的字符串表示形式。
• 返回: <string> 调整后的 object 表示形式。

修饰符#

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

• 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() 在检查对象时将调用该函数并使用其结果。

import { inspect } from 'node:util';

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

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

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

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

const box = new Box(true);

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

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

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

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

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

const box = new Box(true);

console.log(inspect(box));
// "Box< true >"
copy

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

import { inspect } from 'node:util';

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

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

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

console.log(inspect(obj));
// "{ bar: 'baz' }"
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 使用的默认选项。这对于隐式调用 util.inspect 的 console.log 或 util.format 等函数很有用。它应设置为一个包含一个或多个有效 util.inspect() 选项的对象。也支持直接设置选项属性。

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

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

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

util.isDeepStrictEqual(val1, val2[, options])#

• val1 <any>
• val2 <any>
• skipPrototype <boolean> 如果为 true，则在深度严格相等检查期间跳过原型和构造函数比较。默认值: false。
• 返回：<boolean>

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

默认情况下，深度严格相等包括对象原型和构造函数的比较。当 skipPrototype 为 true 时，如果对象的可枚举属性是深度严格相等的，那么具有不同原型或构造函数的对象仍然可以被视为相等。

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

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

class Bar {
  constructor(a) {
    this.a = a;
  }
}

const foo = new Foo(1);
const bar = new Bar(1);

// Different constructors, same properties
console.log(util.isDeepStrictEqual(foo, bar));
// false

console.log(util.isDeepStrictEqual(foo, bar, true));
// true
copy

有关深度严格相等的更多信息，请参阅 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/plain
const { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plain
copy

mime.type#

• 类型：<string>

获取和设置 MIME 的 type 部分。

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

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

mime.subtype#

• 类型：<string>

获取和设置 MIME 的 subtype 部分。

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

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

mime.essence#

• 类型：<string>

获取 MIME 的 essence。此属性是只读的。使用 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=value
const { MIMEType } = require('node:util');

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

mime.params#

• 类型: <MIMEParams>

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

mime.toString()#

• 返回: <string>

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

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

mime.toJSON()#

• 返回: <string>

mime.toString() 的别名。

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

import { MIMEType } from 'node:util';

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

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]
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
//   bar
const { MIMEType } = require('node:util');

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

mimeParams.set(name, value)#

• name <string>
• value <string>

将 MIMEParams 对象中与 name 关联的值设置为 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=xyz
const { MIMEType } = require('node:util');

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

mimeParams.values()#

• 返回: <Iterator>

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

mimeParams[Symbol.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 baz
const { MIMEType } = require('node:util');

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

util.parseArgs([config])#

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

  • args <string[]> 参数字符串数组。默认值: 移除了 execPath 和 filename 的 process.argv。
  • options <Object> 用于描述解析器已知的参数。options 的键是选项的长名称，值是接受以下属性的 <Object>：
    • type <string> 参数类型，必须为 boolean 或 string。
    • multiple <boolean> 此选项是否可以多次提供。如果为 true，则所有值将收集在一个数组中。如果为 false，则选项的值以最后一次为准。默认值: false。
    • short <string> 选项的单字符别名。
    • default <string> | <boolean> | <string[]> | <boolean[]> 如果选项未出现在要解析的参数中，则分配给该选项的值。该值必须匹配 type 属性指定的类型。如果 multiple 为 true，则必须是一个数组。当选项确实出现在要解析的参数中时，不应用默认值，即使提供的值是虚值。
  • strict <boolean> 当遇到未知参数，或传递的参数与 options 中配置的 type 不匹配时，是否应抛出错误。默认值: true。
  • allowPositionals <boolean> 该命令是否接受位置参数。默认值: 如果 strict 为 true 则为 false，否则为 true。
  • allowNegative <boolean> 如果为 true，允许通过在选项名称前加上 --no- 来显式将布尔选项设置为 false。默认值: false。
  • tokens <boolean> 返回已解析的令牌。这对于扩展内置行为（从添加额外的检查到以不同方式重新处理令牌）很有用。默认值: false。

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

  • values <Object> 解析后的选项名称及其 <string> 或 <boolean> 值的映射。
  • positionals <string[]> 位置参数。
  • tokens <Object[]> | <undefined> 请参阅 parseArgs tokens 部分。仅在 config 包含 tokens: true 时返回。

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

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> 选项在参数中如何使用，例如 -f 或 --foo。
  • value <string> | <undefined> 参数中指定的选项值。对于布尔选项为未定义。
  • inlineValue <boolean> | <undefined> 选项值是否以内联方式指定，例如 --foo=bar。
• 位置令牌
  • value <string> 参数中位置参数的值（即 args[index]）。
• 选项终结器令牌

返回的令牌按它们在输入参数中出现的顺序排列。在参数中出现多次的选项会为每次使用生成一个令牌。像 -xy 这样的短选项组会为每个选项展开一个令牌。因此 -xxx 生成三个令牌。

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

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 的版本。

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

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

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

或者，等效地使用 async function

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

const promisifiedStat = promisify(stat);

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

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

const promisifiedStat = promisify(stat);

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

callStat();
copy

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

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

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

import { promisify } from 'node:util';

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

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

const foo = new Foo();

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

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

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'
const { promisify } = require('node:util');

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

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

const foo = new Foo();

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

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

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

自定义 promisified 函数#

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

import { promisify } from 'node:util';

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

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

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

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

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

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