Node.js v21.7.2 文件

util.callbackify(original)#

• original <Function> 一個 async 函式
• 傳回：<Function> 一個 callback 型式的函式

取得一個 async 函式（或一個傳回 Promise 的函式），並傳回一個遵循錯誤優先 callback 型式的函式，也就是將 (err, value) => ... callback 當作最後一個參數。在 callback 中，第一個參數會是拒絕原因（或 null，如果 Promise 已解決），而第二個參數會是已解決的值。

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

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

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

會印出

hello world copy

callback 會以非同步方式執行，而且會有一個受限的堆疊追蹤。如果 callback 擲出，這個程序會發出一個 'uncaughtException' 事件，而且如果沒有處理，就會結束。

由於 null 對 callback 的第一個參數來說具有特殊意義，如果一個包裝函式拒絕一個 Promise，而其原因是一個假值，這個值會包裝在一個 Error 中，而原始值會儲存在一個名為 reason 的欄位中。

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

callbackFunction((err, ret) => {
  // When the Promise was rejected with `null` it is wrapped with an Error and
  // the original value is stored in `reason`.
  err && Object.hasOwn(err, 'reason') && err.reason === null;  // true
}); copy

util.debuglog(section[, callback])#

• section <字串> 識別應用程式區段的字串，用於建立 debuglog 函式。
• callback <函式> 回呼函式，在記錄函式第一次呼叫時呼叫，函式引數是一個最佳化的記錄函式。
• 傳回：<函式> 記錄函式

util.debuglog() 方法用於建立一個函式，根據 NODE_DEBUG 環境變數的存在與否，有條件地將偵錯訊息寫入 stderr。如果 section 名稱出現在該環境變數的值中，則傳回的函式會像 console.error() 一樣運作。如果不是，則傳回的函式會是空運作。

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

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

如果在環境中以 NODE_DEBUG=foo 執行此程式，則會輸出類似以下的內容

FOO 3245: hello from foo [123] copy

其中 3245 是處理序 ID。如果沒有設定該環境變數執行，則不會印出任何內容。

section 也支援萬用字元

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

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

如果在環境中以 NODE_DEBUG=foo* 執行，則會輸出類似以下的內容

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

可以在 NODE_DEBUG 環境變數中指定多個以逗號分隔的 section 名稱：NODE_DEBUG=fs,net,tls。

可選擇的 callback 引數可用於將記錄函式替換為沒有任何初始化或不必要的包裝的不同函式。

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

debuglog().enabled#

• <布林值>

util.debuglog().enabled getter 用於建立一個測試，該測試可根據 NODE_DEBUG 環境變數的存在與否用於條件式中。如果 section 名稱出現在該環境變數的值中，則傳回值會是 true。如果不是，則傳回值會是 false。

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

如果在環境中以 NODE_DEBUG=foo 執行此程式，則會輸出類似以下的內容

hello from foo [123] copy

util.debug(section)#

util.debuglog 的別名。使用時可提高可讀性，僅使用 util.debuglog().enabled 時不表示記錄。

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

• fn <Function> 已棄用的函式。
• msg <string> 呼叫已棄用函式時顯示的警告訊息。
• code <string> 棄用程式碼。請參閱 已棄用 API 清單 以取得程式碼清單。
• 傳回：<Function> 已棄用函式包裝，用於發出警告。

util.deprecate() 方法以標記為已棄用的方式包裝 fn（可能是函式或類別）。

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

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

呼叫時，util.deprecate() 會傳回一個函式，該函式會使用 'warning' 事件發出 DeprecationWarning。第一次呼叫傳回的函式時，會發出警告並印出到 stderr。發出警告後，會呼叫已包裝的函式，而不會發出警告。

如果在多次呼叫 util.deprecate() 時提供相同的選用 code，則只會針對該 code 發出警告一次。

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

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code copy

如果在第一次棄用警告之前使用 --no-deprecation 或 --no-warnings 命令列旗標，或將 process.noDeprecation 屬性設定為 true，則 util.deprecate() 方法不會執行任何動作。

如果設定了 --trace-deprecation 或 --trace-warnings 命令列旗標，或將 process.traceDeprecation 屬性設定為 true，則在第一次呼叫已棄用的函數時，會將警告和堆疊追蹤列印到 stderr。

如果設定了 --throw-deprecation 命令列旗標，或將 process.throwDeprecation 屬性設定為 true，則在呼叫已棄用的函數時，會擲回例外狀況。

--throw-deprecation 命令列旗標和 process.throwDeprecation 屬性優先於 --trace-deprecation 和 process.traceDeprecation。

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

• format <string> 類似 printf 的格式字串。

util.format() 方法會使用第一個參數作為類似於 printf 的格式化字串，其中可以包含零個或多個格式化規格符號。每個規格符號都會以對應參數的轉換值取代。支援的規格符號為

• %s：字串會用於轉換所有值，但 BigInt、物件和 -0 除外。BigInt 值會以 n 表示，而沒有使用者定義 toString 函式的物件會使用 util.inspect() 進行檢查，並搭配選項 { depth: 0, colors: false, compact: 3 }。
• %d：數字會用於轉換所有值，但 BigInt 和 符號 除外。
• %i：parseInt(value, 10) 會用於所有值，但 BigInt 和 符號 除外。
• %f：parseFloat(value) 會用於所有值，但 符號 除外。
• %j：JSON。如果參數包含循環參照，則會以字串 '[Circular]' 取代。
• %o：物件。物件的字串表示形式，採用一般 JavaScript 物件格式化。類似於搭配選項 { showHidden: true, showProxy: true } 的 util.inspect()。這會顯示完整的物件，包括不可列舉的屬性和代理。
• %O：物件。物件的字串表示形式，採用一般 JavaScript 物件格式化。類似於不搭配選項的 util.inspect()。這會顯示完整的物件，但不包括不可列舉的屬性和代理。
• %c：CSS。這個規格符號會被忽略，並會略過傳入的任何 CSS。
• %%：單一百分比符號 ('%')。這不會消耗參數。
• 傳回：<字串> 格式化後的字串

如果規格符號沒有對應的參數，則不會進行取代

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

如果格式化字串中沒有包含的值，則會使用 util.inspect() 格式化這些值，前提是其類型不是 字串。

如果傳遞給 util.format() 方法的參數多於規格說明符的數量，額外的參數會串聯到傳回的字串中，並以空格分隔

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

如果第一個參數不包含有效的格式規格說明符，util.format() 會傳回一個字串，該字串是所有參數的串聯，並以空格分隔

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

如果只傳遞一個參數給 util.format()，它會原樣傳回，不進行任何格式化

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

util.format() 是一個同步方法，用作除錯工具。某些輸入值可能會產生顯著的效能負擔，進而阻擋事件迴圈。請小心使用此函式，且切勿在熱程式碼路徑中使用。

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

• inspectOptions <Object>
• format <string>

此函式與 util.format() 相同，不同之處在於它會接收 inspectOptions 參數，該參數會指定傳遞給 util.inspect() 的選項。

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// Returns 'See object { foo: 42 }', where `42` is colored as a number
// when printed to a terminal. copy

util.getSystemErrorName(err)#

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

傳回來自 Node.js API 的數字錯誤碼的字串名稱。錯誤碼與錯誤名稱之間的對應關係取決於平台。請參閱 常見系統錯誤 以取得常見錯誤的名稱。

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

util.getSystemErrorMap()#

• 傳回：<Map>

傳回一個 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.inherits(constructor, superConstructor)#

• constructor <Function>
• superConstructor <Function>

不建議使用 util.inherits()。請使用 ES6 class 和 extends 關鍵字來取得語言層級的繼承支援。另外請注意，這兩種樣式在語意上不相容。

將一個建構函式的原型方法繼承到另一個建構函式中。constructor 的原型將設定為從 superConstructor 建立的新物件。

這主要是在 Object.setPrototypeOf(constructor.prototype, superConstructor.prototype) 的基礎上新增一些輸入驗證。作為額外的便利，superConstructor 可透過 constructor.super_ 屬性存取。

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

function MyStream() {
  EventEmitter.call(this);
}

util.inherits(MyStream, EventEmitter);

MyStream.prototype.write = function(data) {
  this.emit('data', data);
};

const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('It works!'); // Received data: "It works!" copy

使用 class 和 extends 的 ES6 範例

const EventEmitter = require('node:events');

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

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6'); copy

util.inspect(object[, options])#

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

• object <any> 任何 JavaScript 基本型別或 Object。
• options <Object>
  • showHidden <boolean> 如果為 true，則會在格式化結果中包含 object 的不可列舉符號和屬性。也會包含 WeakMap 和 WeakSet 條目，以及使用者定義的原型屬性（不包含方法屬性）。預設值：false。
  • depth <number> 指定在格式化 object 時要遞迴的次數。這對於檢查大型物件很有用。若要遞迴到最大的呼叫堆疊大小，請傳遞 Infinity 或 null。預設值：2。
  • colors <boolean> 如果為 true，則會使用 ANSI 色碼對輸出進行樣式化。顏色是可以自訂的。請參閱 自訂 util.inspect 顏色。預設值：false。
  • customInspect <boolean> 如果為 false，則不會呼叫 [util.inspect.custom](depth, opts, inspect) 函數。預設值：true。
  • showProxy <boolean> 如果為 true，則 Proxy 檢查會包含 target 和 handler 物件。預設值：false。
  • maxArrayLength <整數> 指定格式化時要包含的 Array、TypedArray、Map、Set、WeakMap 和 WeakSet 元素的最大數量。設定為 null 或 Infinity 以顯示所有元素。設定為 0 或負值以不顯示任何元素。預設：100。
  • maxStringLength <整數> 指定格式化時要包含的最大字元數量。設定為 null 或 Infinity 以顯示所有元素。設定為 0 或負值以不顯示任何字元。預設：10000。
  • breakLength <整數> 輸入值會在這個長度處拆分到多行。設定為 Infinity 以將輸入格式化為單行（與設定為 true 的 compact 或任何大於或等於 1 的數字結合使用）。預設：80。
  • compact <布林值> | <整數> 將此設定為 false 會導致每個物件金鑰顯示在新行。它會在長度超過 breakLength 的文字中換行。如果設定為數字，最多 n 個內部元素會合併到單行，只要所有屬性都符合 breakLength。短陣列元素也會分組在一起。如需更多資訊，請參閱以下範例。預設：3。
  • sorted <布林值> | <函式> 如果設定為 true 或函式，物件的所有屬性以及 Set 和 Map 項目會在結果字串中排序。如果設定為 true，會使用 預設排序。如果設定為函式，會將其用作 比較函式。
  • getters <布林值> | <字串> 如果設為 true，將檢查 getters。如果設為 'get'，則只檢查沒有對應 setter 的 getters。如果設為 'set'，則只檢查有對應 setter 的 getters。這可能會根據 getter 函式造成副作用。預設值：false。
  • numericSeparator <布林值> 如果設為 true，將使用底線分隔所有 bigint 和數字中的每三個位數。預設值：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] {}' copy

循環參照會使用參考索引指向其錨點

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

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

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

以下範例會檢查 util 物件的所有屬性

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

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

以下範例重點說明 compact 選項的效果

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

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

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

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

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

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

showHidden 選項允許檢查 WeakMap 和 WeakSet 項目。如果項目多於 maxArrayLength，則無法保證會顯示哪些項目。這表示重複擷取相同的 WeakSet 項目可能會產生不同的輸出。此外，沒有剩餘強參照的項目可能會隨時被垃圾回收。

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

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

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

sorted 選項可確保物件的屬性插入順序不會影響 util.inspect() 的結果。

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

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

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

numericSeparator 選項會在所有數字的每三個位元組中加入底線。

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

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

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

util.inspect() 是一個用於除錯的同步方法。其最大輸出長度約為 128 MiB。會將導致較長輸出的輸入進行截斷。

自訂 util.inspect 顏色#

util.inspect 的彩色輸出（如果已啟用）可透過 util.inspect.styles 和 util.inspect.colors 屬性進行全域自訂。

util.inspect.styles 是將樣式名稱與 util.inspect.colors 中的顏色關聯起來的對應。

預設樣式和關聯的顏色為

• bigint：yellow
• boolean：yellow
• date：magenta
• module：underline
• name：（無樣式）
• null：bold
• number：yellow
• regexp：red
• special：cyan（例如，Proxies）
• string：green
• symbol：green
• undefined：grey

色彩樣式使用 ANSI 控制碼，可能並非所有終端機都支援。若要驗證色彩支援，請使用 tty.hasColors()。

預先定義的控制碼如下所列（分為「修改器」、「前景顏色」和「背景顏色」）。

修改器#

修改器支援會因不同的終端機而異。如果不支援，它們大多會被忽略。

• reset - 將所有（色彩）修改器重設為其預設值
• bold - 將文字加粗
• italic - 將文字設為斜體
• underline - 將文字加上底線
• strikethrough - 在文字中心加上一條橫線（別名：strikeThrough、crossedout、crossedOut）
• hidden - 印出文字，但使其不可見（別名：conceal）
• dim - 降低色彩強度（別名：faint）
• overlined - 讓文字有上劃線
• blink - 讓文字在間隔中隱藏和顯示
• inverse - 交換前景和背景顏色（別名：swapcolors、swapColors）
• doubleunderline - 讓文字有雙重底線（別名：doubleUnderline）
• framed - 在文字周圍畫一個框

前景顏色#

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• gray（別名：grey、blackBright）
• redBright
• greenBright
• yellowBright
• blueBright
• magentaBright
• cyanBright
• whiteBright

背景顏色#

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite
• bgGray（別名：bgGrey、bgBlackBright）
• bgRedBright
• bgGreenBright
• bgYellowBright
• bgBlueBright
• bgMagentaBright
• bgCyanBright
• bgWhiteBright

物件的自訂檢查函式#

物件也可以定義自己的 [util.inspect.custom](depth, opts, inspect) 函式，util.inspect() 會呼叫此函式，並在檢查物件時使用其結果。

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

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

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

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

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

const box = new Box(true);

util.inspect(box);
// Returns: "Box< true >" copy

自訂的 [util.inspect.custom](depth, opts, inspect) 函式通常會傳回字串，但可以傳回任何類型的值，util.inspect() 會根據此值進行格式化。

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

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

util.inspect(obj);
// Returns: "{ bar: 'baz' }" copy

util.inspect.custom#

• <symbol> 可用於宣告自訂檢查函數。

除了可透過 util.inspect.custom 存取之外，這個符號是 全域註冊，且可在任何環境中以 Symbol.for('nodejs.util.inspect.custom') 存取。

使用這個功能可讓程式碼以可攜式的方式撰寫，以便在 Node.js 環境中使用自訂檢查函數，並在瀏覽器中忽略它。util.inspect() 函數本身會傳遞為自訂檢查函數的第三個引數，以允許進一步的攜式性。

const customInspectSymbol = Symbol.for('nodejs.util.inspect.custom');

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

  toString() {
    return 'xxxxxxxx';
  }

  [customInspectSymbol](depth, inspectOptions, inspect) {
    return `Password <${this.toString()}>`;
  }
}

const password = new Password('r0sebud');
console.log(password);
// Prints Password <xxxxxxxx> copy

請參閱 物件上的自訂檢查函數 以取得更多詳細資料。

util.inspect.defaultOptions#

defaultOptions 值允許自訂 util.inspect 使用的預設選項。這對於會隱式呼叫 util.inspect 的函數（例如 console.log 或 util.format）很有用。它應設定為包含一個或多個有效的 util.inspect() 選項的物件。直接設定選項屬性也受支援。

const util = require('node:util');
const arr = Array(101).fill(0);

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

util.isDeepStrictEqual(val1, val2)#

• val1 <any>
• val2 <any>
• 傳回：<boolean>

如果 val1 和 val2 之間有深度嚴格相等，則傳回 true。否則，傳回 false。

請參閱 assert.deepStrictEqual() 以進一步了解嚴格深度相等性。

類別：util.MIMEType#

MIMEType 類別 的實作。

根據瀏覽器慣例，MIMEType 物件的所有屬性都實作為類別原型上的 getter 和 setter，而不是作為物件本身上的資料屬性。

MIME 字串是一個包含多個有意義組成的結構化字串。解析後，會傳回包含這些組成各個屬性的 MIMEType 物件。

建構函式：new MIMEType(input)#

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

透過解析 input 來建立新的 MIMEType 物件。

import { MIMEType } from 'node:util';

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

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

如果 input 不是有效的 MIME，會擲回 TypeError。請注意，系統會嘗試將給定的值強制轉換為字串。例如

import { MIMEType } from 'node:util';
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plainconst { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plaincopy

mime.type#

• <string>

取得並設定 MIME 的類型部分。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascriptconst { MIMEType } = require('node:util');

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

mime.subtype#

• <string>

取得並設定 MIME 的子類型部分。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascriptconst { MIMEType } = require('node:util');

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

mime.essence#

• <string>

取得 MIME 的精華。此屬性為唯讀。使用 mime.type 或 mime.subtype 來變更 MIME。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=valueconst { MIMEType } = require('node:util');

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

mime.params#

• <MIMEParams>

取得表示 MIME 參數的 MIMEParams 物件。此屬性為唯讀。有關詳細資訊，請參閱 MIMEParams 文件。

mime.toString()#

• 傳回：<string>

MIMEType 物件上的 toString() 方法傳回序列化後的 MIME。

由於需要符合標準，此方法不允許使用者自訂 MIME 的序列化程序。

mime.toJSON()#

• 傳回：<string>

mime.toString() 的別名。

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

移除所有名稱為 name 的名稱值對。

mimeParams.entries()#

• 傳回： <Iterator>

傳回參數中每個名稱值對的迭代器。迭代器的每個項目都是 JavaScript Array。陣列的第一個項目是 name，陣列的第二個項目是 value。

mimeParams.get(name)#

• name <字串>
• 傳回： <string> | <null> 如果沒有名稱為指定 name 的名稱值對，則傳回字串或 null。

傳回名稱為 name 的第一個名稱值對的值。如果沒有此類對應，則傳回 null。

mimeParams.has(name)#

• name <字串>
• 傳回：<boolean>

如果至少有一個名稱為 name 的名稱值對，則傳回 true。

mimeParams.keys()#

• 傳回： <Iterator>

傳回每個名稱值對的名稱的迭代器。

import { MIMEType } from 'node:util';

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

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

mimeParams.set(name, value)#

• name <字串>
• 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=xyzconst { MIMEType } = require('node:util');

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

mimeParams.values()#

• 傳回： <Iterator>

傳回每個名稱/值對值的迭代器。

mimeParams[@@iterator]()#

• 傳回： <Iterator>

mimeParams.entries() 的別名。

import { MIMEType } from 'node:util';

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

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

util.parseArgs([config])#

• config <Object> 用於提供剖析引數和設定剖析器的引數。config 支援下列屬性

  • args <string[]> 引數字串陣列。預設值：已移除 execPath 和 filename 的 process.argv。
  • options <Object> 用於描述剖析器已知的引數。options 的金鑰是引數的長名稱，而值是接受下列屬性的 <Object>
    • type <string> 引數類型，必須是 boolean 或 string。
    • multiple <boolean> 此引數是否可以提供多次。如果為 true，所有值都會收集在陣列中。如果為 false，引數的值會採用最後一個。預設值：false。
    • short <string> 引數的單一字元別名。
    • default <字串> | <布林> | <字串[]> | <布林[]> 當未由 args 設定時，預設選項值。其型別必須與 type 屬性相同。當 multiple 為 true 時，其必須為陣列。
  • strict <布林> 當遇到未知引數或傳遞的引數與 options 中設定的 type 不符時，是否擲回錯誤。預設值：true。
  • allowPositionals <布林> 此指令是否接受位置引數。預設值：如果 strict 為 true，則為 false，否則為 true。
  • tokens <布林> 傳回已剖析的符號。這有助於擴充內建行為，從新增其他檢查到以不同方式重新處理符號。預設值：false。

• 傳回：<物件> 已剖析的命令列引數

  • values <物件> 已剖析的選項名稱對應其 <字串> 或 <布林> 值的對應。
  • positionals <字串陣列> 位置參數。
  • tokens <物件陣列> | <未定義> 請參閱 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 來取得詳細的剖析資訊，以加入自訂行為。傳回的 tokens 具有描述下列內容的屬性

• 所有 tokens
  • kind <字串> '選項'、'位置' 或 '選項終止符' 之一。
  • index <數字> 包含 token 的 args 中的元素索引。因此 token 的原始參數為 args[token.index]。
• 選項 tokens
  • name <字串> 選項的長名稱。
  • rawName <字串> 選項在 args 中的使用方式，例如 --foo 的 -f。
  • value <字串> | <未定義> 在 args 中指定的選項值。布林選項為未定義。
  • inlineValue <布林> | <未定義> 選項值是否內嵌指定，例如 --foo=bar。
• 位置參數
  • value <string> args 中位置參數的值（即 args[index]）。
• 選項終止符參數

傳回的參數依據在輸入 args 中遇到的順序排列。在 args 中出現多次的選項會為每次使用產生一個參數。像 -xy 這樣的短選項群組會擴充為每個選項的一個參數。因此 -xxx 會產生三個參數。

例如，若要使用傳回的參數來新增對否定選項（例如 --no-color）的支援，可以重新處理參數以變更儲存的否定選項值。

import { parseArgs } from 'node:util';

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

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

console.log({ logfile, color });const { parseArgs } = require('node:util');

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

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

console.log({ logfile, color });copy

範例用法，顯示否定選項，以及當選項以多種方式使用時，最後一個會獲勝。

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

util.parseEnv(content)#

• content <string>

.env 檔案的原始內容。

• 傳回：<Object>

假設有一個範例 .env 檔案

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

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }import { parseEnv } from 'node:util';

parseEnv('HELLO=world\nHELLO=oh my\n');
// Returns: { HELLO: 'oh my' }copy

util.promisify(original)#

• original <Function>
• 傳回：<Function>

採用遵循常見錯誤優先回呼樣式的函式，亦即將 (err, value) => ... 回呼作為最後一個引數，並傳回傳送承諾的版本。

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

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

或者，等效地使用 async function

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

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

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

callStat(); copy

如果存在 original[util.promisify.custom] 屬性，promisify 會傳回其值，請參閱 自訂承諾函式。

promisify() 假設 original 在所有情況下都是將回呼作為最後一個引數的函式。如果 original 不是函式，promisify() 會擲回錯誤。如果 original 是函式，但其最後一個引數不是錯誤優先回呼，它仍會將錯誤優先回呼傳遞為其最後一個引數。

除非特別處理，否則在類別方法或使用 this 的其他方法上使用 promisify() 可能無法按預期運作

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

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

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

const foo = new Foo();

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

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

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

自訂承諾函式#

使用 util.promisify.custom 符號，可以覆寫 util.promisify() 的傳回值

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

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

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

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

這對於原始函式不遵循將錯誤優先回呼作為最後一個引數的標準格式的情況很有用。

例如，使用採用 (foo, onSuccessCallback, onErrorCallback) 的函式

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

如果定義了 promisify.custom 但它不是函式，promisify() 會擲回錯誤。

util.promisify.custom#

• <symbol>，可用於宣告函式的自訂承諾變體，請參閱 自訂承諾函式。

除了可透過 util.promisify.custom 存取之外，此符號也 已在全球註冊，且可在任何環境中作為 Symbol.for('nodejs.util.promisify.custom') 存取。

例如，使用採用 (foo, onSuccessCallback, onErrorCallback) 的函式

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

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

util.stripVTControlCharacters(str)#

• str <字串>
• 傳回：<string>

傳回已移除任何 ANSI 跳脫碼的 str。

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

util.styleText(format, text)#

• format <字串> 在 util.inspect.colors 中定義的文字格式。
• text <字串> 要格式化的文字。

此函式會傳回考量傳入的 format 的格式化文字。

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

util.inspect.colors 也提供文字格式，例如 斜體 和 底線，而且你可以結合兩者

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

可以在 modifiers 中找到格式的完整清單。

類別：util.TextDecoder#

TextDecoder API 的 WHATWG 編碼標準 實作。

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

WHATWG 支援的編碼#

根據 WHATWG 編碼標準，TextDecoder API 支援的編碼在以下表格中列出。對於每個編碼，可以使用一個或多個別名。

不同的 Node.js 建置組態支援不同的編碼組。（請參閱 國際化）

預設支援的編碼（含完整 ICU 資料）#

編碼在 Node.js 使用 small-icu 選項建置時獲得支援#

當 ICU 停用時支援的編碼#

WHATWG 編碼標準 中所列的 'iso-8859-16' 編碼不受支援。

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

• encoding <string> 識別此 TextDecoder 實例支援的 encoding。預設值： 'utf-8'。
• options <Object>
  • fatal <boolean> 如果解碼失敗為致命錯誤，則為 true。當 ICU 停用時，此選項不受支援（請參閱 國際化）。預設值： false。
  • ignoreBOM <boolean> 當為 true 時，TextDecoder 會在解碼結果中包含位元組順序標記。當為 false 時，位元組順序標記會從輸出中移除。此選項僅在 encoding 為 'utf-8'、'utf-16be' 或 'utf-16le' 時使用。預設值： false。

建立新的 TextDecoder 實例。encoding 可以指定一種支援的編碼或別名。

TextDecoder 類別也出現在全域物件中。

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

• input <ArrayBuffer> | <DataView> | <TypedArray> 包含編碼資料的 ArrayBuffer、DataView 或 TypedArray 實例。
• options <Object>
  • stream <boolean> 如果預期有其他資料區塊，則為 true。預設值：false。
• 傳回：<string>

解碼 input 並傳回字串。如果 options.stream 為 true，則 input 結尾處發生的任何不完整位元組序列會在內部進行緩衝，並在下次呼叫 textDecoder.decode() 後發出。

如果 textDecoder.fatal 為 true，則發生的解碼錯誤將導致擲出 TypeError。

textDecoder.encoding#

• <string>

TextDecoder 實例支援的編碼。

textDecoder.fatal#

• <布林值>

如果解碼錯誤導致擲出 TypeError，則值為 true。

textDecoder.ignoreBOM#

• <布林值>

如果解碼結果將包含位元組順序標記，則值為 true。

類別：util.TextEncoder#

WHATWG 編碼標準 TextEncoder API 的實作。所有 TextEncoder 實例僅支援 UTF-8 編碼。

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

TextEncoder 類別也可用於全域物件。

textEncoder.encode([input])#

• input <字串> 要編碼的文字。預設值：空白字串。
• 傳回：<Uint8Array>

使用 UTF-8 編碼 input 字串，並傳回包含已編碼位元組的 Uint8Array。

textEncoder.encodeInto(src, dest)#

• src <字串> 要編碼的文字。
• dest <Uint8Array> 用於儲存編碼結果的陣列。
• 傳回：<Object>
  • read <數字> src 的已讀 Unicode 編碼單位。
  • written <數字> dest 的已寫入 UTF-8 位元組。

將 src 字串使用 UTF-8 編碼到 dest Uint8Array，並傳回包含已讀 Unicode 編碼單位和已寫入 UTF-8 位元組的物件。

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

textEncoder.encoding#

• <string>

TextEncoder 實例支援的編碼。始終設定為 'utf-8'。

util.toUSVString(string)#

• 字串 <字串>

傳回在用 Unicode「替換字元」U+FFFD 取代任何代理代碼點（或等效地，任何未配對的代理代碼單位）後的字串。

util.transferableAbortController()#

建立並傳回一個 <AbortController> 實例，其 <AbortSignal> 標記為可傳輸，並可用於 structuredClone() 或 postMessage()。

util.transferableAbortSignal(signal)#

• signal <AbortSignal>
• 傳回：<AbortSignal>

將指定的 <AbortSignal> 標記為可傳輸，以便可用於 structuredClone() 和 postMessage()。

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

util.aborted(signal, resource)#

• signal <AbortSignal>
• resource <物件> 任何非空實體，對其的參照是弱保留的。
• 傳回：<承諾>

監聽所提供的 signal 上的中止事件，並傳回一個承諾，在 signal 中止時會履行。如果傳遞的 resource 在 signal 中止之前被垃圾回收，傳回的承諾將無限期地保持待處理狀態。

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

const dependent = obtainSomethingAbortable();

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

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

const dependent = obtainSomethingAbortable();

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

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

util.types#

util.types 提供內建物件不同類型的類型檢查。與 instanceof 或 Object.prototype.toString.call(value) 不同，這些檢查不會檢查物件中可從 JavaScript 存取的屬性（例如其原型），且通常會產生呼叫 C++ 的開銷。

結果通常不會對值在 JavaScript 中公開的屬性或行為類型做出任何保證。它們主要對偏好於在 JavaScript 中執行類型檢查的附加元件開發人員有用。

可透過 require('node:util').types 或 require('node:util/types') 存取 API。

util.types.isAnyArrayBuffer(value)#

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

如果值是內建的 ArrayBuffer 或 SharedArrayBuffer 執行個體，則傳回 true。

另請參閱 util.types.isArrayBuffer() 和 util.types.isSharedArrayBuffer()。

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

util.types.isArrayBufferView(value)#

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

如果值是 ArrayBuffer 檢視之一的執行個體，例如類型化陣列物件或 DataView，則傳回 true。等同於 ArrayBuffer.isView()。

util.types.isArrayBufferView(new Int8Array());  // true
util.types.isArrayBufferView(Buffer.from('hello world')); // true
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16)));  // true
util.types.isArrayBufferView(new ArrayBuffer());  // false copy

util.types.isArgumentsObject(value)#

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

如果值是 arguments 物件，則傳回 true。

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

util.types.isArrayBuffer(value)#

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

如果值是內建 ArrayBuffer 執行個體，則傳回 true。這不包含 SharedArrayBuffer 執行個體。通常，最好同時測試這兩者；請參閱 util.types.isAnyArrayBuffer()。

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

util.types.isAsyncFunction(value)#

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

如果值是 非同步函式，則傳回 true。這只回報 JavaScript 引擎看到的內容；特別是，如果使用了轉譯工具，傳回值可能與原始原始碼不符。

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

util.types.isBigInt64Array(value)#

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

如果值是 BigInt64Array 執行個體，則傳回 true。

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

util.types.isBigUint64Array(value)#

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

如果值是 BigUint64Array 執行個體，則傳回 true。

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

util.types.isBooleanObject(value)#

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

如果值是布林物件，例如由 new Boolean() 建立，則傳回 true。

util.types.isBooleanObject(false);  // Returns false
util.types.isBooleanObject(true);   // Returns false
util.types.isBooleanObject(new Boolean(false)); // Returns true
util.types.isBooleanObject(new Boolean(true));  // Returns true
util.types.isBooleanObject(Boolean(false)); // Returns false
util.types.isBooleanObject(Boolean(true));  // Returns false copy

util.types.isBoxedPrimitive(value)#

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

如果值是任何裝箱基本型物件，例如由 new Boolean()、new String() 或 Object(Symbol()) 建立，則傳回 true。

例如

util.types.isBoxedPrimitive(false); // Returns false
util.types.isBoxedPrimitive(new Boolean(false)); // Returns true
util.types.isBoxedPrimitive(Symbol('foo')); // Returns false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true
util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true copy

util.types.isCryptoKey(value)#

• value <Object>
• 傳回：<boolean>

如果 value 是 <CryptoKey>，則傳回 true，否則傳回 false。

util.types.isDataView(value)#

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

如果值是內建 DataView 執行個體，則傳回 true。

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

另請參閱 ArrayBuffer.isView()。

util.types.isDate(value)#

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

如果值是內建 Date 執行個體，則傳回 true。

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

util.types.isExternal(value)#

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

如果值是原生 External 值，則傳回 true。

原生 External 值是一種特殊類型的物件，其中包含一個原始 C++ 指標 (void*) 以供原生程式碼存取，且沒有其他屬性。此類物件是由 Node.js 內部或原生外掛程式所建立。在 JavaScript 中，它們是具有 null 原型的 凍結 物件。

#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
  int* raw = (int*) malloc(1024);
  napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
  if (status != napi_ok) {
    napi_throw_error(env, NULL, "napi_create_external failed");
    return NULL;
  }
  return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
... copy

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

如需有關 napi_create_external 的更多資訊，請參閱 napi_create_external()。

util.types.isFloat32Array(value)#

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

如果值是內建 Float32Array 執行個體，則傳回 true。

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

util.types.isFloat64Array(value)#

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

如果值是內建 Float64Array 執行個體，則傳回 true。

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

util.types.isGeneratorFunction(value)#

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

如果值是產生器函式，則傳回 true。這只回報 JavaScript 引擎所看到的內容；特別是，如果使用了轉譯工具，傳回值可能與原始原始碼不符。

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

util.types.isGeneratorObject(value)#

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

如果值是從內建產生器函式傳回的產生器物件，則傳回 true。這只回報 JavaScript 引擎所看到的內容；特別是，如果使用了轉譯工具，傳回值可能與原始原始碼不符。

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

util.types.isInt8Array(value)#

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

如果值是內建的 Int8Array 執行個體，則傳回 true。

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

util.types.isInt16Array(value)#

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

如果值是內建的 Int16Array 執行個體，則傳回 true。

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

util.types.isInt32Array(value)#

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

如果值是內建的 Int32Array 執行個體，則傳回 true。

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

util.types.isKeyObject(value)#

• value <Object>
• 傳回：<boolean>

如果 value 是 <KeyObject>，則傳回 true，否則傳回 false。

util.types.isMap(value)#

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

如果值是內建的 Map 執行個體，則傳回 true。

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

util.types.isMapIterator(value)#

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

如果值是內建的 Map 執行個體所傳回的迭代器，則傳回 true。

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

util.types.isModuleNamespaceObject(value)#

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

如果值是 模組命名空間物件 的執行個體，則傳回 true。

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

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

util.types.isNativeError(value)#

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

如果值是由內建Error 類型的建構函式傳回，則傳回 true。

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

原生錯誤類型的子類別也是原生錯誤

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

值為原生錯誤類別的 instanceof 並不等於 isNativeError() 為該值傳回 true。isNativeError() 會為來自不同領域的錯誤傳回 true，而 instanceof Error 會為這些錯誤傳回 false

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

相反地，isNativeError() 會為所有並非由原生錯誤建構函式傳回的物件傳回 false。這包括為原生錯誤的 instanceof 的值

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

util.types.isNumberObject(value)#

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

如果值是數字物件（例如，由 new Number() 建立），則傳回 true。

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

util.types.isPromise(value)#

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

如果值是內建Promise，則傳回 true。

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

util.types.isProxy(value)#

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

如果值是Proxy實例，則傳回 true。

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

util.types.isRegExp(value)#

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

如果值是正規表示式物件，則傳回 true。

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

util.types.isSet(value)#

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

如果值是內建Set實例，則傳回 true。

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

util.types.isSetIterator(value)#

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

如果值是為內建Set實例傳回的迭代器，則傳回 true。

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

util.types.isSharedArrayBuffer(value)#

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

如果值是內建的 SharedArrayBuffer 執行個體，則傳回 true。這不包含 ArrayBuffer 執行個體。通常，最好同時測試這兩者；請參閱 util.types.isAnyArrayBuffer()。

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

util.types.isStringObject(value)#

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

如果值是字串物件，例如由 new String() 建立，則傳回 true。

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

util.types.isSymbolObject(value)#

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

如果值是符號物件，透過在 Symbol 原生型別上呼叫 Object() 建立，則傳回 true。

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

util.types.isTypedArray(value)#

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

如果值是內建的 TypedArray 執行個體，則傳回 true。

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

另請參閱 ArrayBuffer.isView()。

util.types.isUint8Array(value)#

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

如果值是內建的 Uint8Array 執行個體，則傳回 true。

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

util.types.isUint8ClampedArray(value)#

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

如果值是內建的 Uint8ClampedArray 執行個體，則傳回 true。

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

util.types.isUint16Array(value)#

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

如果值是內建的 Uint16Array 執行個體，則傳回 true。

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

util.types.isUint32Array(value)#

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

如果值是內建的 Uint32Array 執行個體，則傳回 true。

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

util.types.isWeakMap(value)#

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

如果值是內建的 WeakMap 執行個體，則傳回 true。

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

util.types.isWeakSet(value)#

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

如果值是內建的 WeakSet 執行個體，則傳回 true。

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

已棄用的 API#

下列 API 已棄用，不應再使用。現有的應用程式和模組應更新為尋找替代方法。

util._extend(target, source)#

• target <Object>
• source <Object>

util._extend() 方法從未打算在 Node.js 內部模組以外使用。社群發現並使用它。

它已棄用，不應在新的程式碼中使用。JavaScript 透過 Object.assign() 提供非常類似的內建功能。

util.isArray(object)#

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

Array.isArray() 的別名。

如果給定的 object 是 Array，則傳回 true。否則，傳回 false。

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

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

util.isBoolean(object)#

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

如果給定的 object 是 Boolean，則傳回 true。否則，傳回 false。

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

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

util.isBuffer(object)#

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

如果給定的 object 是 Buffer，則傳回 true。否則，傳回 false。

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

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

util.isDate(object)#

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

如果給定的 object 是 Date，則傳回 true。否則，傳回 false。

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

util.isDate(new Date());
// Returns: true
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({});
// Returns: false copy

util.isError(object)#

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

如果給定的 object 是 Error，則傳回 true。否則，傳回 false。

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

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

此方法依賴於 Object.prototype.toString() 行為。當 object 參數操作 @@toStringTag 時，可能會取得不正確的結果。

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

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

util.isFunction(object)#

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

如果給定的 object 是 Function，則傳回 true。否則，傳回 false。

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

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

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

util.isNull(object)#

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

如果給定的 object 是嚴格的 null，則傳回 true。否則，傳回 false。

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

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

util.isNullOrUndefined(object)#

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

如果給定的 object 是 null 或 undefined，則傳回 true。否則，傳回 false。

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

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

util.isNumber(object)#

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

如果給定的 object 是 Number，則傳回 true。否則，傳回 false。

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

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

util.isObject(object)#

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

如果給定的 object 嚴格來說是一個 Object 而且 不是一個 Function（即使在 JavaScript 中函式是物件）。否則，傳回 false。

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

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

util.isPrimitive(object)#

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

如果給定的 object 是原始類型，則傳回 true。否則，傳回 false。

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

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

util.isRegExp(object)#

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

如果給定的 object 是 RegExp，則傳回 true。否則，傳回 false。

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

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

util.isString(object)#

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

如果給定的 object 是 string，則傳回 true。否則，傳回 false。

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

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

util.isSymbol(object)#

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

如果給定的 object 是 Symbol，則傳回 true。否則，傳回 false。

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

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

util.isUndefined(object)#

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

如果給定的 object 為 undefined，則傳回 true。否則，傳回 false。

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

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

util.log(string)#

• 字串 <字串>

util.log() 方法會將給定的 string 列印至 stdout，並包含時間戳記。

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

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