Util

[稳定: 2 - 稳定]

node:util 模块支持 Node.js 内部 API 的需求。许多实用程序对于应用程序和模块开发人员也很有用。访问它：

const util = require('node:util')

`util.callbackify(original)`

添加到: v8.2.0

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

接受一个 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)
})

将打印：

text

hello world

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

由于 null 作为回调的第一个参数具有特殊含义，如果包装函数拒绝使用虚假值作为原因的 Promise，则该值将被包装在 Error 中，原始值存储在名为 reason 的字段中。

function fn() {
  return Promise.reject(null)
}
const callbackFunction = util.callbackify(fn)

callbackFunction((err, ret) => {
  // 当 Promise 被拒绝为 `null` 时，它将被包装在一个 Error 中，
  // 原始值存储在 `reason` 中。
  err && Object.hasOwn(err, 'reason') && err.reason === null // true
})

`util.debuglog(section[, callback])`

新增于: v0.11.3

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)

如果该程序在设置了 NODE_DEBUG=foo 的环境中运行，则它将输出类似以下内容：

bash

FOO 3245: hello from foo [123]

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

section 也支持通配符：

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

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

如果在设置了 NODE_DEBUG=foo* 的环境中运行，则它将输出类似以下内容：

bash

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

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

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

const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
  // 使用优化了是否启用 section 测试的日志函数替换
  debuglog = debug
})

`debuglog().enabled`

新增于：v14.9.0

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

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

bash

hello from foo [123]

`util.debug(section)`

新增于：v14.9.0

util.debuglog 的别名。这种用法提高了可读性，避免了仅使用 util.debuglog().enabled 时暗示日志记录的情况。

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

[历史]

版本	变更
v10.0.0	每个代码的弃用警告仅发出一次。
v0.8.0	新增于：v0.8.0

fn <Function> 即将弃用的函数。
msg <string> 调用弃用函数时显示的警告消息。
code <string> 弃用代码。有关代码列表，请参见弃用 API 列表。
返回值: <Function> 用于发出警告的已弃用函数包装器。

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

const util = require('node:util')

exports.obsoleteFunction = util.deprecate(() => {
  // 在此处执行某些操作。
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.')

调用时，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() // 使用代码 DEP0001 发出弃用警告
fn2() // 不会发出弃用警告，因为它具有相同的代码

如果使用了 --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])`

[历史]

版本	变更
v12.11.0	`%c` 说明符现已忽略。
v12.0.0	只有当 `format` 参数实际包含格式说明符时，才将其作为格式说明符处理。
v12.0.0	如果 `format` 参数不是格式字符串，则输出字符串的格式不再依赖于第一个参数的类型。此更改删除了当第一个参数不是字符串时输出字符串中先前存在的引号。
v11.4.0	`%d`、`%f` 和 `%i` 说明符现在正确支持 Symbol。
v11.4.0	`%o` 说明符的 `depth` 默认深度恢复为 4。
v11.0.0	`%o` 说明符的 `depth` 选项现在将回退到默认深度。
v10.12.0	`%d` 和 `%i` 说明符现在支持 BigInt。
v8.4.0	现在支持 `%o` 和 `%O` 说明符。
v0.5.3	新增于：v0.5.3

format <字符串> 一个类似 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 对象格式的对象的字符串表示形式。类似于使用选项 { showHidden: true, showProxy: true } 的 util.inspect()。这将显示完整对象，包括不可枚举属性和代理。
%O: Object。具有通用 JavaScript 对象格式的对象的字符串表示形式。类似于不带选项的 util.inspect()。这将显示完整对象，不包括不可枚举属性和代理。
%c: CSS。此说明符将被忽略，并将跳过任何传入的 CSS。
%%: 单个百分号 ('%')。这不会使用参数。
返回值: <字符串> 格式化的字符串

如果说明符没有对应的参数，则不会替换它：

util.format('%s:%s', 'foo')
// 返回：'foo:%s'

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

如果传递给 util.format() 方法的参数多于说明符的数量，则将额外的参数连接到返回的字符串中，并用空格分隔：

util.format('%s:%s', 'foo', 'bar', 'baz')
// 返回：'foo:bar baz'

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

util.format(1, 2, 3)
// 返回：'1 2 3'

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

util.format('%% %s')
// 返回：'%% %s'

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

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

新增于: v10.0.0

inspectOptions <Object>
format <string>

此函数与 util.format() 相同，不同之处在于它接受一个 inspectOptions 参数，该参数指定传递给 util.inspect() 的选项。

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 })
// 返回 'See object { foo: 42 }'，其中 `42` 在打印到终端时将被着色为数字。

`util.getCallSites(frameCountOrOptions, [options])`

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1.1 - 主动开发中

[历史]

版本	变更
v23.3.0	API 从 `util.getCallSite` 重命名为 `util.getCallSites()`。
v22.9.0	新增于: v22.9.0

frameCount <number> 可选，捕获为调用站点对象的帧数。默认值: 10。允许的范围是 1 到 200 之间。
options <Object> 可选
- sourceMap <boolean> 从源映射重建堆栈跟踪中的原始位置。使用标志 --enable-source-maps 默认启用。
返回: <Object[]> 一个调用站点对象的数组
- functionName <string> 返回与此调用站点关联的函数的名称。
- scriptName <string> 返回包含此调用站点函数脚本的资源的名称。
- lineNumber <number> 返回关联函数调用的行的编号（基于 1）。
- column <number> 返回关联函数调用在行上的基于 1 的列偏移量。

返回一个调用站点对象的数组，其中包含调用函数的堆栈。

const util = require('node:util')

function exampleFunction() {
  const callSites = util.getCallSites()

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

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

  // ...
}

// 模拟另一个堆栈层的函数
function anotherFunction() {
  exampleFunction()
}

anotherFunction()

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

import util from 'node:util'

interface Foo {
  foo: string
}

const callSites = util.getCallSites({ sourceMap: true })

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

// 不使用 sourceMap:
// Function Name: ''
// Script Name: example.js
// Line Number: 2
// Column Number: 26

`util.getSystemErrorName(err)`

新增于: v9.7.0

err <number>
返回值: <string>

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

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

`util.getSystemErrorMap()`

新增于: v16.0.0, v14.17.0

返回值: <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
})

`util.getSystemErrorMessage(err)`

新增于: v23.1.0

err <number>
返回值: <string>

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

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

`util.inherits(constructor, superConstructor)`

[历史]

版本	变更
v5.0.0	`constructor` 参数现在可以引用 ES6 类。
v0.3.0	新增于: v0.3.0

[稳定性: 3 - 已弃用]

稳定性: 3 稳定性: 3 - 已弃用: 请改用 ES2015 类语法和 extends 关键字。

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

使用 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')

`util.inspect(object[, options])`

`util.inspect(object[, showHidden[, depth[, colors]]])`

[历史]

版本	变更
v16.18.0	添加对检查 `Set` 和 `Map` 时 `maxArrayLength` 的支持。
v17.3.0, v16.14.0	现在支持 `numericSeparator` 选项。
v13.0.0	循环引用现在包含一个指向引用的标记。
v14.6.0, v12.19.0	如果 `object` 来自不同的 `vm.Context`，则其上的自定义检查函数将不再接收特定于上下文的参数。
v13.13.0, v12.17.0	现在支持 `maxStringLength` 选项。
v13.5.0, v12.16.0	如果 `showHidden` 为 `true`，则会检查用户定义的原型属性。
v12.0.0	`compact` 选项的默认值更改为 `3`，`breakLength` 选项的默认值更改为 `80`。
v12.0.0	内部属性不再出现在自定义检查函数的上下文参数中。
v11.11.0	`compact` 选项接受数字以用于新的输出模式。
v11.7.0	ArrayBuffers 现在也显示其二进制内容。
v11.5.0	现在支持 `getters` 选项。
v11.4.0	`depth` 默认值更改回 `2`。
v11.0.0	`depth` 默认值更改为 `20`。
v11.0.0	检查输出现在限制在大约 128 MiB。超过此大小的数据将不会被完全检查。
v10.12.0	现在支持 `sorted` 选项。
v10.6.0	现在可以检查链接列表和类似对象，直到最大调用栈大小。
v10.0.0	现在也可以检查 `WeakMap` 和 `WeakSet` 条目。
v9.9.0	现在支持 `compact` 选项。
v6.6.0	自定义检查函数现在可以返回 `this`。
v6.3.0	现在支持 `breakLength` 选项。
v6.1.0	现在支持 `maxArrayLength` 选项；特别是，长数组默认情况下会被截断。
v6.1.0	现在支持 `showProxy` 选项。
v0.3.0	添加于：v0.3.0

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

循环引用通过使用引用索引指向其锚点：

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

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

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

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

const util = require('node:util')

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

以下示例重点介绍了 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' } }

// 将 `compact` 设置为 false 或整数会创建更易于阅读的输出。
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'
//   }
// }

// 将 `breakLength` 设置为例如 150 将在一行中打印“Lorem ipsum”文本。

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

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

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

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

对象的自定义检查函数

[历史]

版本	变更
v17.3.0, v16.14.0	添加了 `inspect` 参数以增强互操作性。
v0.1.97	在 v0.1.97 版本中添加

对象也可以定义自己的 [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,
    })

    // 五个空格填充，因为 "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)
// 返回： "Box< true >"

自定义 [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)
// 返回： "{ bar: 'baz' }"

`util.inspect.custom`

[历史]

版本	变更
v10.12.0	此属性现已定义为共享符号。
v6.6.0	新增于：v6.6.0

<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)
// 打印 Password <xxxxxxxx>

参见对象上的自定义检查函数获取更多详细信息。

`util.inspect.defaultOptions`

新增于：v6.4.0

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) // 输出被截断的数组
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // 输出完整的数组

`util.isDeepStrictEqual(val1, val2)`

新增于：v9.0.0

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

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

参见 assert.deepStrictEqual() 以了解有关深度严格相等的更多信息。

类: `util.MIMEType`

新增于: v19.1.0, v18.13.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

MIMEType 类的实现。

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

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

构造函数: `new MIMEType(input)`

input <string> 要解析的输入 MIME

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

ESMCJS

import { MIMEType } from 'node:util'

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

const { MIMEType } = require('node:util')

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

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

ESMCJS

import { MIMEType } from 'node:util'
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// 打印: text/plain

const { MIMEType } = require('node:util')
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// 打印: text/plain

`mime.type`

<字符串>

获取和设置 MIME 的类型部分。

ESMCJS

import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// 输出：text
myMIME.type = 'application'
console.log(myMIME.type)
// 输出：application
console.log(String(myMIME))
// 输出：application/javascript

const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// 输出：text
myMIME.type = 'application'
console.log(myMIME.type)
// 输出：application
console.log(String(myMIME))
// 输出：application/javascript

`mime.subtype`

<字符串>

获取和设置 MIME 的子类型部分。

ESMCJS

import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// 输出：ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// 输出：javascript
console.log(String(myMIME))
// 输出：text/javascript

const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// 输出：ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// 输出：javascript
console.log(String(myMIME))
// 输出：text/javascript

`mime.essence`

<字符串>

获取 MIME 的本质。此属性为只读。使用 mime.type 或 mime.subtype 来更改 MIME。

ESMCJS

import { MIMEType } from 'node:util'

const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// 输出：text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// 输出：application/javascript
console.log(String(myMIME))
// 输出：application/javascript;key=value

const { MIMEType } = require('node:util')

const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// 输出：text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// 输出：application/javascript
console.log(String(myMIME))
// 输出：application/javascript;key=value

`mime.params`

<MIMEParams>

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

`mime.toString()`

返回值: <字符串>

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

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

`mime.toJSON()`

返回值: <字符串>

mime.toString() 的别名。

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

ESMCJS

import { MIMEType } from 'node:util'

const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// 输出: ["image/png", "image/gif"]

const { MIMEType } = require('node:util')

const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// 输出: ["image/png", "image/gif"]

类: `util.MIMEParams`

新增于: v19.1.0, v18.13.0

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

构造函数: `new MIMEParams()`

创建一个参数为空的新 MIMEParams 对象。

ESMCJS

import { MIMEParams } from 'node:util'

const myParams = new MIMEParams()

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

const myParams = new MIMEParams()

`mimeParams.delete(name)`

name <字符串>

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

`mimeParams.entries()`

返回值: <迭代器>

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

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

ESMCJS

import { MIMEType } from 'node:util'

const { params } = new MIMEType('text/plain;foo=0;bar=1')
for (const name of params.keys()) {
  console.log(name)
}
// 打印：
//   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)
}
// 打印：
//   foo
//   bar

`mimeParams.set(name, value)`

name <字符串>
value <字符串>

将 MIMEParams 对象中与 name 关联的值设置为 value。如果存在任何名称为 name 的现有名称-值对，则将第一个此类对的值设置为 value。

ESMCJS

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())
// 输出：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())
// 输出：foo=def;bar=1;baz=xyz

`mimeParams.values()`

返回值：<迭代器>

返回一个迭代器，用于遍历每个名称-值对的值。

`mimeParams[@@iterator]()`

返回值：<Iterator>

[mimeParams.entries()](/zh/api/util#mimeparamsentries) 的别名。

ESMCJS

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)
}
// 输出：
//   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)
}
// 输出：
//   foo bar
//   xyz baz

`util.parseArgs([config])`

[历史]

版本	变更
v22.4.0, v20.16.0	添加对在输入 `config` 中允许负选项的支持。
v20.0.0	此 API 不再是实验性的。
v18.11.0, v16.19.0	添加对在输入 `config` 中使用默认值的支持。
v18.7.0, v16.17.0	添加对使用输入 `config` 中的 `tokens` 返回详细解析信息的支持以及返回的属性。
v18.3.0, v16.17.0	新增于：v18.3.0, v16.17.0

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 令牌部分。仅当 config 包含 tokens: true 时才返回。

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

ESMCJS

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)
// 输出： [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)
// 输出： [Object: null prototype] { foo: true, bar: 'b' } []

`parseArgs` `tokens`

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

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

返回的 tokens 按照输入 args 中遇到的顺序排列。在 args 中多次出现的选项会为每次使用生成一个 token。像 -xy 这样的短选项组会扩展为每个选项的一个 token。因此 -xxx 会生成三个 tokens。

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

ESMCJS

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

// 重新处理选项 tokens 并覆盖返回的值。
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // 为 --no-foo 存储 foo:false
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // 重新保存值，以便如果同时使用 --foo 和 --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 })

// 重新处理选项 tokens 并覆盖返回的值。
tokens
  .filter(token => token.kind === 'option')
  .forEach(token => {
    if (token.name.startsWith('no-')) {
      // 为 --no-foo 存储 foo:false
      const positiveName = token.name.slice(3)
      values[positiveName] = false
      delete values[token.name]
    } else {
      // 重新保存值，以便如果同时使用 --foo 和 --no-foo，则最后一个值胜出。
      values[token.name] = token.value ?? true
    }
  })

const color = values.color
const logfile = values.logfile ?? 'default.log'

console.log({ logfile, color })

显示否定选项以及当以多种方式使用选项时最后一个选项胜出的示例用法。

bash

$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false }

`util.parseEnv(content)`

[稳定版: 1 - 实验性]

稳定版: 1 稳定性: 1.1 - 活跃开发中

新增于: v21.7.0, v20.12.0

content <字符串>

.env 文件的原始内容。

返回值: <对象>

给定一个 .env 文件示例：

CJSESM

const { parseEnv } = require('node:util')

parseEnv('HELLO=world\nHELLO=oh my\n')
// 返回值: { HELLO: 'oh my' }

import { parseEnv } from 'node:util'

parseEnv('HELLO=world\nHELLO=oh my\n')
// 返回值: { HELLO: 'oh my' }

`util.promisify(original)`

[历史]

版本	变更
v20.8.0	调用返回 Promise 的函数的 `promisify` 已弃用。
v8.0.0	新增于: v8.0.0

original <函数>
返回值: <函数>

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

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

const stat = util.promisify(fs.stat)
stat('.')
  .then(stats => {
    // 使用 `stats` 执行某些操作
  })
  .catch(error => {
    // 处理错误。
  })

或者，等效地使用 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(`此目录归 ${stats.uid} 所有`)
}

callStat()

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

自定义 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])
// 打印 'true'

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

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

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

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

`util.promisify.custom`

[历史]

版本	变更
v13.12.0, v12.16.2	现在定义为共享符号。
v8.0.0	新增于：v8.0.0

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

`util.stripVTControlCharacters(str)`

新增于: v16.11.0

str <string>
返回值: <string>

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

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'))
// 输出 "value"

`util.styleText(format, text[, options])`

[稳定: 2 - 稳定]

稳定: 2 稳定性: 2 - 稳定。

[历史]

版本	变更
v23.5.0	styleText 现已稳定。
v22.8.0, v20.18.0	尊重 isTTY 和环境变量，例如 NO_COLORS、NODE_DISABLE_COLORS 和 FORCE_COLOR。
v21.7.0, v20.12.0	新增于: v21.7.0, v20.12.0

format <string> | <Array> util.inspect.colors 中定义的文本格式或文本格式数组。
text <string> 要格式化的文本。
options <Object>
- validateStream <boolean> 当为 true 时，检查 stream 是否可以处理颜色。默认值: true。
- stream <Stream> 如果可以着色，则验证的流。默认值: process.stdout。

此函数返回考虑到的 format 的格式化文本，以便在终端中打印。它知道终端的功能，并根据通过 NO_COLORS、NODE_DISABLE_COLORS 和 FORCE_COLOR 环境变量设置的配置进行操作。

ESMCJS

import { styleText } from 'node:util'
import { stderr } from 'node:process'

const successMessage = styleText('green', 'Success!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // 验证 process.stderr 是否有 TTY
  { stream: stderr }
)
console.error(successMessage)

const { styleText } = require('node:util')
const { stderr } = require('node:process')

const successMessage = styleText('green', 'Success!')
console.log(successMessage)

const errorMessage = styleText(
  'red',
  'Error! Error!',
  // 验证 process.stderr 是否有 TTY
  { stream: stderr }
)
console.error(successMessage)

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

console.log(util.styleText(['underline', 'italic'], 'My italic underlined message'))

当传递一个格式数组时，应用格式的顺序是从左到右，因此以下样式可能会覆盖之前的样式。

console.log(
  util.styleText(['red', 'green'], 'text') // green
)

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

类: `util.TextDecoder`

[历史]

版本	变更
v11.0.0	此类现在可在全局对象上使用。
v8.3.0	新增于：v8.3.0

WHATWG 编码标准 TextDecoder API 的实现。

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

WHATWG 支持的编码

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

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

默认支持的编码（具有完整的 ICU 数据）

编码	别名
`'ibm866'`	`'866'` , `'cp866'` , `'csibm866'`
`'iso-8859-2'`	`'csisolatin2'` , `'iso-ir-101'` , `'iso8859-2'` , `'iso88592'` , `'iso_8859-2'` , `'iso_8859-2:1987'` , `'l2'` , `'latin2'`
`'iso-8859-3'`	`'csisolatin3'` , `'iso-ir-109'` , `'iso8859-3'` , `'iso88593'` , `'iso_8859-3'` , `'iso_8859-3:1988'` , `'l3'` , `'latin3'`
`'iso-8859-4'`	`'csisolatin4'` , `'iso-ir-110'` , `'iso8859-4'` , `'iso88594'` , `'iso_8859-4'` , `'iso_8859-4:1988'` , `'l4'` , `'latin4'`
`'iso-8859-5'`	`'csisolatincyrillic'` , `'cyrillic'` , `'iso-ir-144'` , `'iso8859-5'` , `'iso88595'` , `'iso_8859-5'` , `'iso_8859-5:1988'`
`'iso-8859-6'`	`'arabic'` , `'asmo-708'` , `'csiso88596e'` , `'csiso88596i'` , `'csisolatinarabic'` , `'ecma-114'` , `'iso-8859-6-e'` , `'iso-8859-6-i'` , `'iso-ir-127'` , `'iso8859-6'` , `'iso88596'` , `'iso_8859-6'` , `'iso_8859-6:1987'`
`'iso-8859-7'`	`'csisolatingreek'` , `'ecma-118'` , `'elot_928'` , `'greek'` , `'greek8'` , `'iso-ir-126'` , `'iso8859-7'` , `'iso88597'` , `'iso_8859-7'` , `'iso_8859-7:1987'` , `'sun_eu_greek'`
`'iso-8859-8'`	`'csiso88598e'` , `'csisolatinhebrew'` , `'hebrew'` , `'iso-8859-8-e'` , `'iso-ir-138'` , `'iso8859-8'` , `'iso88598'` , `'iso_8859-8'` , `'iso_8859-8:1988'` , `'visual'`
`'iso-8859-8-i'`	`'csiso88598i'` , `'logical'`
`'iso-8859-10'`	`'csisolatin6'` , `'iso-ir-157'` , `'iso8859-10'` , `'iso885910'` , `'l6'` , `'latin6'`
`'iso-8859-13'`	`'iso8859-13'` , `'iso885913'`
`'iso-8859-14'`	`'iso8859-14'` , `'iso885914'`
`'iso-8859-15'`	`'csisolatin9'` , `'iso8859-15'` , `'iso885915'` , `'iso_8859-15'` , `'l9'`
`'koi8-r'`	`'cskoi8r'` , `'koi'` , `'koi8'` , `'koi8_r'`
`'koi8-u'`	`'koi8-ru'`
`'macintosh'`	`'csmacintosh'` , `'mac'` , `'x-mac-roman'`
`'windows-874'`	`'dos-874'` , `'iso-8859-11'` , `'iso8859-11'` , `'iso885911'` , `'tis-620'`
`'windows-1250'`	`'cp1250'` , `'x-cp1250'`
`'windows-1251'`	`'cp1251'` , `'x-cp1251'`
`'windows-1252'`	`'ansi_x3.4-1968'` , `'ascii'` , `'cp1252'` , `'cp819'` , `'csisolatin1'` , `'ibm819'` , `'iso-8859-1'` , `'iso-ir-100'` , `'iso8859-1'` , `'iso88591'` , `'iso_8859-1'` , `'iso_8859-1:1987'` , `'l1'` , `'latin1'` , `'us-ascii'` , `'x-cp1252'`
`'windows-1253'`	`'cp1253'` , `'x-cp1253'`
`'windows-1254'`	`'cp1254'` , `'csisolatin5'` , `'iso-8859-9'` , `'iso-ir-148'` , `'iso8859-9'` , `'iso88599'` , `'iso_8859-9'` , `'iso_8859-9:1989'` , `'l5'` , `'latin5'` , `'x-cp1254'`
`'windows-1255'`	`'cp1255'` , `'x-cp1255'`
`'windows-1256'`	`'cp1256'` , `'x-cp1256'`
`'windows-1257'`	`'cp1257'` , `'x-cp1257'`
`'windows-1258'`	`'cp1258'` , `'x-cp1258'`
`'x-mac-cyrillic'`	`'x-mac-ukrainian'`
`'gbk'`	`'chinese'` , `'csgb2312'` , `'csiso58gb231280'` , `'gb2312'` , `'gb_2312'` , `'gb_2312-80'` , `'iso-ir-58'` , `'x-gbk'`
`'gb18030'`
`'big5'`	`'big5-hkscs'` , `'cn-big5'` , `'csbig5'` , `'x-x-big5'`
`'euc-jp'`	`'cseucpkdfmtjapanese'` , `'x-euc-jp'`
`'iso-2022-jp'`	`'csiso2022jp'`
`'shift_jis'`	`'csshiftjis'` , `'ms932'` , `'ms_kanji'` , `'shift-jis'` , `'sjis'` , `'windows-31j'` , `'x-sjis'`
`'euc-kr'`	`'cseuckr'` , `'csksc56011987'` , `'iso-ir-149'` , `'korean'` , `'ks_c_5601-1987'` , `'ks_c_5601-1989'` , `'ksc5601'` , `'ksc_5601'` , `'windows-949'`

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

编码	别名
`'utf-8'`	`'unicode-1-1-utf-8'` , `'utf8'`
`'utf-16le'`	`'utf-16'`
`'utf-16be'`

禁用 ICU 时支持的编码

编码	别名
`'utf-8'`	`'unicode-1-1-utf-8'` , `'utf8'`
`'utf-16le'`	`'utf-16'`

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

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

encoding <字符串> 标识此 TextDecoder 实例支持的 encoding。默认值：'utf-8'。
options <对象>
- fatal <布尔值> 如果解码失败是致命的，则为 true。禁用 ICU 时不支持此选项（请参见国际化）。默认值：false。
- ignoreBOM <布尔值> 当 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`

<字符串>

TextDecoder 实例支持的编码。

`textDecoder.fatal`

<布尔值>

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

`textDecoder.ignoreBOM`

<布尔值>

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

类: `util.TextEncoder`

[历史]

版本	变更
v11.0.0	该类现在可在全局对象上使用。
v8.3.0	新增于：v8.3.0

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

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

TextEncoder 类也可在全局对象上使用。

`textEncoder.encode([input])`

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

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

`textEncoder.encodeInto(src, dest)`

新增于：v12.11.0

src <string> 待编码文本。
dest <Uint8Array> 用于保存编码结果的数组。
返回值：<Object>
- 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)

`textEncoder.encoding`

<字符串>

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

`util.toUSVString(string)`

新增于：v16.8.0, v14.18.0

string <字符串>

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

`util.transferableAbortController()`

新增于：v18.11.0

[稳定版：1 - 实验性]

稳定版：1 稳定性：1 - 实验性

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

`util.transferableAbortSignal(signal)`

新增于：v18.11.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

signal <AbortSignal>
返回值：<AbortSignal>

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

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

`util.aborted(signal, resource)`

新增于：v19.7.0, v18.16.0

[稳定性：1 - 实验性]

稳定性：1 稳定性：1 - 实验性

signal <AbortSignal>
resource <Object> 任何与可中止操作关联的非空对象，并被弱引用。如果在 signal 中止之前 resource 被垃圾回收，则 promise 保持挂起状态，允许 Node.js 停止跟踪它。这有助于防止长期运行或不可取消操作中的内存泄漏。
返回值：<Promise>

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

CJSESM

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

// 获取具有可中止信号的对象，例如自定义资源或操作。
const dependent = obtainSomethingAbortable()

// 将 `dependent` 作为资源传递，表明只有在 `signal` 中止时 `dependent` 仍在内存中时，promise 才会解析。
aborted(dependent.signal, dependent).then(() => {
  // 当 `dependent` 中止时，此代码运行。
  console.log('Dependent resource was aborted.')
})

// 模拟触发中止的事件。
dependent.on('event', () => {
  dependent.abort() // 这将导致 `aborted` promise 解析。
})

import { aborted } from 'node:util'

// 获取具有可中止信号的对象，例如自定义资源或操作。
const dependent = obtainSomethingAbortable()

// 将 `dependent` 作为资源传递，表明只有在 `signal` 中止时 `dependent` 仍在内存中时，promise 才会解析。
aborted(dependent.signal, dependent).then(() => {
  // 当 `dependent` 中止时，此代码运行。
  console.log('Dependent resource was aborted.')
})

// 模拟触发中止的事件。
dependent.on('event', () => {
  dependent.abort() // 这将导致 `aborted` promise 解析。
})

`util.types`

[历史]

版本	变更
v15.3.0	作为 `require('util/types')` 导出。
v10.0.0	v10.0.0 中添加

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)`

添加于：v10.0.0

value <任何>
返回：<布尔值>

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

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

util.types.isAnyArrayBuffer(new ArrayBuffer()) // 返回 true
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // 返回 true

`util.types.isArrayBufferView(value)`

新增于：v10.0.0

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

`util.types.isArgumentsObject(value)`

Added in: v10.0.0

value <any>
Returns: <boolean>

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

function foo() {
  util.types.isArgumentsObject(arguments) // 返回 true
}

`util.types.isArrayBuffer(value)`

Added in: v10.0.0

value <any>
Returns: <boolean>

如果值为内置 ArrayBuffer 实例，则返回 true。这不包括 SharedArrayBuffer 实例。通常情况下，需要同时测试两者；详见 util.types.isAnyArrayBuffer()。

util.types.isArrayBuffer(new ArrayBuffer()) // 返回 true
util.types.isArrayBuffer(new SharedArrayBuffer()) // 返回 false

`util.types.isAsyncFunction(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isAsyncFunction(function foo() {}) // 返回 false
util.types.isAsyncFunction(async function foo() {}) // 返回 true

`util.types.isBigInt64Array(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isBigInt64Array(new BigInt64Array()) // 返回 true
util.types.isBigInt64Array(new BigUint64Array()) // 返回 false

`util.types.isBigIntObject(value)`

新增于：v10.4.0

value <any>
返回值: <boolean>

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

util.types.isBigIntObject(Object(BigInt(123))) // 返回 true
util.types.isBigIntObject(BigInt(123)) // 返回 false
util.types.isBigIntObject(123) // 返回 false

`util.types.isBigUint64Array(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isBigUint64Array(new BigInt64Array()) // 返回 false
util.types.isBigUint64Array(new BigUint64Array()) // 返回 true

`util.types.isBooleanObject(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isBooleanObject(false) // 返回 false
util.types.isBooleanObject(true) // 返回 false
util.types.isBooleanObject(new Boolean(false)) // 返回 true
util.types.isBooleanObject(new Boolean(true)) // 返回 true
util.types.isBooleanObject(Boolean(false)) // 返回 false
util.types.isBooleanObject(Boolean(true)) // 返回 false

`util.types.isBoxedPrimitive(value)`

新增于: v10.11.0

value <any>
返回值: <boolean>

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

例如：

util.types.isBoxedPrimitive(false) // 返回 false
util.types.isBoxedPrimitive(new Boolean(false)) // 返回 true
util.types.isBoxedPrimitive(Symbol('foo')) // 返回 false
util.types.isBoxedPrimitive(Object(Symbol('foo'))) // 返回 true
util.types.isBoxedPrimitive(Object(BigInt(5))) // 返回 true

`util.types.isCryptoKey(value)`

新增于: v16.2.0

value <Object>
返回值: <boolean>

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

`util.types.isDataView(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

const ab = new ArrayBuffer(20)
util.types.isDataView(new DataView(ab)) // 返回 true
util.types.isDataView(new Float64Array()) // 返回 false

另见 ArrayBuffer.isView().

`util.types.isDate(value)`

Added in: v10.0.0

value <any>
Returns: <boolean>

返回 true 如果值为内置 Date 实例。

util.types.isDate(new Date()) // 返回 true

`util.types.isExternal(value)`

Added in: v10.0.0

value <any>
Returns: <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)
...

const native = require('napi_addon.node')
const data = native.myNapi()
util.types.isExternal(data) // 返回 true
util.types.isExternal(0) // 返回 false
util.types.isExternal(new String('foo')) // 返回 false

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

`util.types.isFloat32Array(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isFloat32Array(new ArrayBuffer()) // 返回 false
util.types.isFloat32Array(new Float32Array()) // 返回 true
util.types.isFloat32Array(new Float64Array()) // 返回 false

`util.types.isFloat64Array(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isFloat64Array(new ArrayBuffer()) // 返回 false
util.types.isFloat64Array(new Uint8Array()) // 返回 false
util.types.isFloat64Array(new Float64Array()) // 返回 true

`util.types.isGeneratorFunction(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isGeneratorFunction(function foo() {}) // 返回 false
util.types.isGeneratorFunction(function* foo() {}) // 返回 true

`util.types.isGeneratorObject(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

function* foo() {}
const generator = foo()
util.types.isGeneratorObject(generator) // 返回 true

`util.types.isInt8Array(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isInt8Array(new ArrayBuffer()) // 返回 false
util.types.isInt8Array(new Int8Array()) // 返回 true
util.types.isInt8Array(new Float64Array()) // 返回 false

`util.types.isInt16Array(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isInt16Array(new ArrayBuffer()) // 返回 false
util.types.isInt16Array(new Int16Array()) // 返回 true
util.types.isInt16Array(new Float64Array()) // 返回 false

`util.types.isInt32Array(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isInt32Array(new ArrayBuffer()) // 返回 false
util.types.isInt32Array(new Int32Array()) // 返回 true
util.types.isInt32Array(new Float64Array()) // 返回 false

`util.types.isKeyObject(value)`

新增于: v16.2.0

value <Object>
返回值: <boolean>

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

`util.types.isMap(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isMap(new Map()) // 返回 true

`util.types.isMapIterator(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

const map = new Map()
util.types.isMapIterator(map.keys()) // 返回 true
util.types.isMapIterator(map.values()) // 返回 true
util.types.isMapIterator(map.entries()) // 返回 true
util.types.isMapIterator(map[Symbol.iterator]()) // 返回 true

`util.types.isModuleNamespaceObject(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

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

util.types.isModuleNamespaceObject(ns) // 返回 true

`util.types.isNativeError(value)`

新增于：v10.0.0

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

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

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

一个值是原生错误类的 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

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

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

`util.types.isNumberObject(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isNumberObject(0) // 返回 false
util.types.isNumberObject(new Number(0)) // 返回 true

`util.types.isPromise(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isPromise(Promise.resolve(42)) // 返回 true

`util.types.isProxy(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

const target = {}
const proxy = new Proxy(target, {})
util.types.isProxy(target) // 返回 false
util.types.isProxy(proxy) // 返回 true

`util.types.isRegExp(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isRegExp(/abc/) // 返回 true
util.types.isRegExp(new RegExp('abc')) // 返回 true

`util.types.isSet(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isSet(new Set()) // 返回 true

`util.types.isSetIterator(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

const set = new Set()
util.types.isSetIterator(set.keys()) // 返回 true
util.types.isSetIterator(set.values()) // 返回 true
util.types.isSetIterator(set.entries()) // 返回 true
util.types.isSetIterator(set[Symbol.iterator]()) // 返回 true

`util.types.isSharedArrayBuffer(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

如果值为内置的 SharedArrayBuffer 实例，则返回 true。这不包括 ArrayBuffer 实例。通常情况下，需要同时测试两者；为此，请参见 util.types.isAnyArrayBuffer()。

util.types.isSharedArrayBuffer(new ArrayBuffer()) // 返回 false
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // 返回 true

`util.types.isStringObject(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isStringObject('foo') // 返回 false
util.types.isStringObject(new String('foo')) // 返回 true

`util.types.isSymbolObject(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

如果该值为符号对象（通过调用 Symbol 原型的 Object() 方法创建），则返回 true。

const symbol = Symbol('foo')
util.types.isSymbolObject(symbol) // 返回 false
util.types.isSymbolObject(Object(symbol)) // 返回 true

`util.types.isTypedArray(value)`

新增于：v10.0.0

value <any>
返回值: <boolean>

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

util.types.isTypedArray(new ArrayBuffer()) // 返回 false
util.types.isTypedArray(new Uint8Array()) // 返回 true
util.types.isTypedArray(new Float64Array()) // 返回 true

另见 ArrayBuffer.isView().

`util.types.isUint8Array(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isUint8Array(new ArrayBuffer()) // 返回 false
util.types.isUint8Array(new Uint8Array()) // 返回 true
util.types.isUint8Array(new Float64Array()) // 返回 false

`util.types.isUint8ClampedArray(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isUint8ClampedArray(new ArrayBuffer()) // 返回 false
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // 返回 true
util.types.isUint8ClampedArray(new Float64Array()) // 返回 false

`util.types.isUint16Array(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isUint16Array(new ArrayBuffer()) // 返回 false
util.types.isUint16Array(new Uint16Array()) // 返回 true
util.types.isUint16Array(new Float64Array()) // 返回 false

`util.types.isUint32Array(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isUint32Array(new ArrayBuffer()) // 返回 false
util.types.isUint32Array(new Uint32Array()) // 返回 true
util.types.isUint32Array(new Float64Array()) // 返回 false

`util.types.isWeakMap(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isWeakMap(new WeakMap()) // 返回 true

`util.types.isWeakSet(value)`

新增于: v10.0.0

value <any>
返回值: <boolean>

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

util.types.isWeakSet(new WeakSet()) // 返回 true

已弃用 API

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

`util._extend(target, source)`

新增于：v0.7.5

自 v6.0.0 起已弃用

[稳定性: 0 - 已弃用]

稳定性: 0 稳定性: 0 - 已弃用：请改用 Object.assign()。

target <对象>
source <对象>

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

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

`util.isArray(object)`

新增于：v0.6.0

自 v4.0.0 起已弃用

[稳定性: 0 - 已弃用]

稳定性: 0 稳定性: 0 - 已弃用：请改用 Array.isArray()。

object <任何>
返回值: <布尔值>

Array.isArray() 的别名。

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

const util = require('node:util')

util.isArray([])
// 返回：true
util.isArray(new Array())
// 返回：true
util.isArray({})
// 返回：false

Util ​

util.callbackify(original) ​

util.debuglog(section[, callback]) ​

debuglog().enabled ​

util.debug(section) ​

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

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

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

util.getCallSites(frameCountOrOptions, [options]) ​

util.getSystemErrorName(err) ​

util.getSystemErrorMap() ​

util.getSystemErrorMessage(err) ​

util.inherits(constructor, superConstructor) ​

util.inspect(object[, options]) ​

util.inspect(object[, showHidden[, depth[, colors]]]) ​

自定义 util.inspect 颜色 ​

修饰符 ​

前景色 ​

背景色 ​

对象的自定义检查函数 ​

util.inspect.custom ​

util.inspect.defaultOptions ​

util.isDeepStrictEqual(val1, val2) ​

类: util.MIMEType ​

构造函数: new MIMEType(input) ​

mime.type ​

mime.subtype ​

mime.essence ​

mime.params ​

mime.toString() ​

mime.toJSON() ​

类: util.MIMEParams ​

构造函数: new MIMEParams() ​

mimeParams.delete(name) ​

mimeParams.entries() ​

mimeParams.get(name) ​

mimeParams.has(name) ​

mimeParams.keys() ​

mimeParams.set(name, value) ​

mimeParams.values() ​

mimeParams[@@iterator]() ​

util.parseArgs([config]) ​

parseArgs tokens ​

util.parseEnv(content) ​

util.promisify(original) ​

自定义 Promise 化函数 ​

util.promisify.custom ​

util.stripVTControlCharacters(str) ​

util.styleText(format, text[, options]) ​

类: util.TextDecoder ​

WHATWG 支持的编码 ​

默认支持的编码（具有完整的 ICU 数据） ​

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

禁用 ICU 时支持的编码 ​

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

textDecoder.decode([input[, options]]) ​

textDecoder.encoding ​

textDecoder.fatal ​

textDecoder.ignoreBOM ​

类: util.TextEncoder ​

textEncoder.encode([input]) ​

textEncoder.encodeInto(src, dest) ​

textEncoder.encoding ​

util.toUSVString(string) ​

util.transferableAbortController() ​

util.transferableAbortSignal(signal) ​

util.aborted(signal, resource) ​

util.types ​

util.types.isAnyArrayBuffer(value) ​

util.types.isArrayBufferView(value) ​

util.types.isArgumentsObject(value) ​

util.types.isArrayBuffer(value) ​

util.types.isAsyncFunction(value) ​

util.types.isBigInt64Array(value) ​

util.types.isBigIntObject(value) ​

util.types.isBigUint64Array(value) ​

util.types.isBooleanObject(value) ​

util.types.isBoxedPrimitive(value) ​

util.types.isCryptoKey(value) ​

util.types.isDataView(value) ​

Util

`util.callbackify(original)`

`util.debuglog(section[, callback])`

`debuglog().enabled`

`util.debug(section)`

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

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

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

`util.getCallSites(frameCountOrOptions, [options])`

`util.getSystemErrorName(err)`

`util.getSystemErrorMap()`

`util.getSystemErrorMessage(err)`

`util.inherits(constructor, superConstructor)`

`util.inspect(object[, options])`

`util.inspect(object[, showHidden[, depth[, colors]]])`

自定义 `util.inspect` 颜色

修饰符

前景色

背景色

对象的自定义检查函数

`util.inspect.custom`

`util.inspect.defaultOptions`

`util.isDeepStrictEqual(val1, val2)`

类: `util.MIMEType`

构造函数: `new MIMEType(input)`

`mime.type`

`mime.subtype`

`mime.essence`

`mime.params`

`mime.toString()`

`mime.toJSON()`

类: `util.MIMEParams`

构造函数: `new MIMEParams()`

`mimeParams.delete(name)`

`mimeParams.entries()`

`mimeParams.get(name)`

`mimeParams.has(name)`

`mimeParams.keys()`

`mimeParams.set(name, value)`

`mimeParams.values()`

`mimeParams[@@iterator]()`

`util.parseArgs([config])`

`parseArgs` `tokens`

`util.parseEnv(content)`

`util.promisify(original)`

自定义 Promise 化函数

`util.promisify.custom`

`util.stripVTControlCharacters(str)`

`util.styleText(format, text[, options])`

类: `util.TextDecoder`

WHATWG 支持的编码

默认支持的编码（具有完整的 ICU 数据）

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

禁用 ICU 时支持的编码

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

`textDecoder.decode([input[, options]])`

`textDecoder.encoding`

`textDecoder.fatal`

`textDecoder.ignoreBOM`

类: `util.TextEncoder`

`textEncoder.encode([input])`

`textEncoder.encodeInto(src, dest)`

`textEncoder.encoding`

`util.toUSVString(string)`

`util.transferableAbortController()`

`util.transferableAbortSignal(signal)`

`util.aborted(signal, resource)`

`util.types`

`util.types.isAnyArrayBuffer(value)`

`util.types.isArrayBufferView(value)`

`util.types.isArgumentsObject(value)`

`util.types.isArrayBuffer(value)`

`util.types.isAsyncFunction(value)`

`util.types.isBigInt64Array(value)`

`util.types.isBigIntObject(value)`

`util.types.isBigUint64Array(value)`

`util.types.isBooleanObject(value)`

`util.types.isBoxedPrimitive(value)`

`util.types.isCryptoKey(value)`

`util.types.isDataView(value)`