Node.js v26.0.0 說明文件

全域物件#

這些物件在所有模組中皆可使用。

以下變數看起來像是全域的，但實際上並非如此。它們僅存在於 CommonJS 模組 的作用域內。

• __dirname
• __filename
• exports
• module
• require()

此處列出的物件是 Node.js 特有的。還有一些 JavaScript 語言本身的一部分 內建物件，它們也可以全域存取。

__dirname#

此變數看起來像是全域的，但實際上並非如此。請參見 __dirname。

__filename#

此變數看起來像是全域的，但實際上並非如此。請參見 __filename。

類別：AbortController#

一個工具類別，用於在特定的 Promise 基礎 API 中發出取消信號。此 API 基於 Web API <AbortController>。

const ac = new AbortController();

ac.signal.addEventListener('abort', () => console.log('Aborted!'),
                           { once: true });

ac.abort();

console.log(ac.signal.aborted);  // Prints true
copy

abortController.abort([reason])#

• reason <any> 選用的原因，可透過 AbortSignal 的 reason 屬性取得。

觸發中止信號，導致 abortController.signal 發出 'abort' 事件。

abortController.signal#

• 類型：<AbortSignal>

類別：AbortSignal#

• 繼承：<EventTarget>

AbortSignal 用於在呼叫 abortController.abort() 方法時通知觀察者。

靜態方法：AbortSignal.abort([reason])#

• reason <any>
• 回傳：<AbortSignal>

回傳一個新的且已經處於中止狀態的 AbortSignal。

靜態方法：AbortSignal.timeout(delay)#

• delay <number> 觸發 AbortSignal 前要等待的毫秒數。

回傳一個新的 AbortSignal，它將在 delay 毫秒後中止。

靜態方法：AbortSignal.any(signals)#

• signals <AbortSignal[]> 用於組成新 AbortSignal 的 AbortSignal 陣列。

回傳一個新的 AbortSignal，如果提供的任何信號被中止，它也會跟著中止。它的 abortSignal.reason 將被設定為導致其中止的那個 signals 的原因。

事件：'abort'#

當呼叫 abortController.abort() 方法時，會發出 'abort' 事件。回呼函式被調用時會傳入一個單一物件參數，該物件有一個 type 屬性被設定為 'abort'。

const ac = new AbortController();

// Use either the onabort property...
ac.signal.onabort = () => console.log('aborted!');

// Or the EventTarget API...
ac.signal.addEventListener('abort', (event) => {
  console.log(event.type);  // Prints 'abort'
}, { once: true });

ac.abort();
copy

與 AbortSignal 關聯的 AbortController 只會觸發一次 'abort' 事件。建議在新增 'abort' 事件接聽器之前，先檢查 abortSignal.aborted 屬性是否為 false。

任何附加到 AbortSignal 的事件接聽器都應該使用 { once: true } 選項（或者，如果使用 EventEmitter API 附加接聽器，則使用 once() 方法），以確保在處理完 'abort' 事件後立即移除事件接聽器。若不這樣做，可能會導致記憶體洩漏。

abortSignal.aborted#

• 類型：<boolean>

在 AbortController 中止後為 True。

abortSignal.onabort#

• 類型：<Function>

一個選用的回呼函式，可由使用者程式碼設定，以便在呼叫 abortController.abort() 函式時獲得通知。

abortSignal.reason#

• 類型：<any>

觸發 AbortSignal 時指定的選用原因。

const ac = new AbortController();
ac.abort(new Error('boom!'));
console.log(ac.signal.reason);  // Error: boom!
copy

abortSignal.throwIfAborted()#

如果 abortSignal.aborted 為 true，則拋出 abortSignal.reason。

atob(data)#

buffer.atob() 的全域別名。

提供自動化遷移工具 (原始碼)。

npx codemod@latest @nodejs/buffer-atob-btoa
copy

類別：Blob#

請參見 <Blob>。

類別：BroadcastChannel#

請參見 <BroadcastChannel>。

btoa(data)#

buffer.btoa() 的全域別名。

提供自動化遷移工具 (原始碼)。

npx codemod@latest @nodejs/buffer-atob-btoa
copy

類別：Buffer#

• 類型：<Function>

用於處理二進位數據。請參見 buffer 章節。

類別：ByteLengthQueuingStrategy#

瀏覽器相容的 ByteLengthQueuingStrategy 實作。

clearImmediate(immediateObject)#

clearImmediate 已在 timers (計時器) 章節中說明。

clearInterval(intervalObject)#

clearInterval 已在 timers (計時器) 章節中說明。

clearTimeout(timeoutObject)#

clearTimeout 已在 timers (計時器) 章節中說明。

類別：CloseEvent#

瀏覽器相容的 <CloseEvent> 實作。使用 --no-experimental-websocket CLI 旗標可停用此 API。

類別：CompressionStream#

瀏覽器相容的 CompressionStream 實作。

console#

• 類型：<Object>

用於列印到 stdout 和 stderr。請參見 console 章節。

類別：CountQueuingStrategy#

瀏覽器相容的 CountQueuingStrategy 實作。

類別：Crypto#

瀏覽器相容的 <Crypto> 實作。此全域變數僅在 Node.js 二進位檔編譯時包含 node:crypto 模組支援的情況下才可用。

crypto#

瀏覽器相容的 Web Crypto API 實作。

類別：CryptoKey#

瀏覽器相容的 <CryptoKey> 實作。此全域變數僅在 Node.js 二進位檔編譯時包含 node:crypto 模組支援的情況下才可用。

類別：CustomEvent#

瀏覽器相容的 <CustomEvent> 實作。

類別：DecompressionStream#

瀏覽器相容的 DecompressionStream 實作。

類別：DOMException#

WHATWG <DOMException> 類別。

ErrorEvent#

瀏覽器相容的 <ErrorEvent> 實作。

類別：Event#

瀏覽器相容的 Event 類別實作。有關更多詳細資訊，請參見 EventTarget 與 Event API。

類別：EventSource#

瀏覽器相容的 <EventSource> 實作。

類別：EventTarget#

瀏覽器相容的 EventTarget 類別實作。有關更多詳細資訊，請參見 EventTarget 與 Event API。

exports#

此變數看起來像是全域的，但實際上並非如此。請參見 exports。

fetch#

瀏覽器相容的 fetch() 函式實作。

const res = await fetch('https://nodejs.com.tw/api/documentation.json');
if (res.ok) {
  const data = await res.json();
  console.log(data);
}
copy

此實作基於 undici，這是一個為 Node.js 從頭編寫的 HTTP/1.1 用戶端。您可以透過讀取 process.versions.undici 屬性來瞭解 Node.js 進程中隨附的 undici 版本。

自訂發送器 (Dispatcher)#

您可以透過在 fetch 的選項物件中傳遞自訂發送器來分派請求。發送器必須與 undici 的 Dispatcher 類別 相容。

fetch(url, { dispatcher: new MyAgent() });
copy

在 Node.js 中，可以藉由安裝 undici 並使用 setGlobalDispatcher() 方法來更改全域發送器。呼叫此方法會同時影響 undici 和 Node.js。

import { setGlobalDispatcher } from 'undici';
setGlobalDispatcher(new MyAgent());
copy

相關類別#

以下全域變數可用於 fetch：

• FormData
• Headers
• Request
• Response

類別：File#

請參見 <File>。

類別：FormData#

瀏覽器相容的 <FormData> 實作。

global#

• 類型：<Object> 全域命名空間物件。

在瀏覽器中，頂層作用域傳統上就是全域作用域。這意味著 var something 會定義一個新的全域變數，但在 ECMAScript 模組中除外。在 Node.js 中則不同。頂層作用域並非全域作用域；Node.js 模組內部的 var something 將僅限於該模組本地，無論它是 CommonJS 模組 還是 ECMAScript 模組。

類別：Headers#

瀏覽器相容的 <Headers> 實作。

localStorage#

瀏覽器相容的 localStorage 實作。數據以未加密方式儲存在 --localstorage-file CLI 旗標指定的檔案中。可儲存的數據上限為 10 MB。不支援在 Web Storage API 之外對此數據進行任何修改。在伺服器環境下使用時，localStorage 數據不會按使用者或按請求個別儲存，而是由所有使用者和請求共享。

類別：MessageChannel#

MessageChannel 類別。有關更多詳細資訊，請參見 MessageChannel。

類別：MessageEvent#

瀏覽器相容的 <MessageEvent> 實作。

類別：MessagePort#

MessagePort 類別。有關更多詳細資訊，請參見 MessagePort。

module#

此變數看起來像是全域的，但實際上並非如此。請參見 module。

類別：Navigator#

Navigator API 的部分實作。

navigator#

window.navigator 的部分實作。

navigator.hardwareConcurrency#

• 類型：<number>

navigator.hardwareConcurrency 唯讀屬性會回傳目前 Node.js 實例可用的邏輯處理器數量。

console.log(`This process is running on ${navigator.hardwareConcurrency} logical processors`);
copy

navigator.language#

• 類型：<string>

navigator.language 唯讀屬性會回傳一個代表 Node.js 實例偏好語言的字串。語言將由 Node.js 在執行階段使用的 ICU 程式庫根據作業系統的預設語言決定。

該值代表 RFC 5646 中定義的語言版本。

在沒有 ICU 的版本中，回退值為 'en-US'。

console.log(`The preferred language of the Node.js instance has the tag '${navigator.language}'`);
copy

navigator.languages#

• 類型：<string[]>

navigator.languages 唯讀屬性會回傳一個字串陣列，代表 Node.js 實例偏好的語言。預設情況下 navigator.languages 僅包含 navigator.language 的值，該值將由 Node.js 在執行階段使用的 ICU 程式庫根據作業系統的預設語言決定。

在沒有 ICU 的版本中，回退值為 ['en-US']。

console.log(`The preferred languages are '${navigator.languages}'`);
copy

navigator.locks#

navigator.locks 唯讀屬性會回傳一個 LockManager 實例，可用於協調對同一程序內多個執行緒之間可能共享的資源存取。此全域實作符合 瀏覽器 LockManager API 的語義。

// Request an exclusive lock
await navigator.locks.request('my_resource', async (lock) => {
  // The lock has been acquired.
  console.log(`Lock acquired: ${lock.name}`);
  // Lock is automatically released when the function returns
});

// Request a shared lock
await navigator.locks.request('shared_resource', { mode: 'shared' }, async (lock) => {
  // Multiple shared locks can be held simultaneously
  console.log(`Shared lock acquired: ${lock.name}`);
});
// Request an exclusive lock
navigator.locks.request('my_resource', async (lock) => {
  // The lock has been acquired.
  console.log(`Lock acquired: ${lock.name}`);
  // Lock is automatically released when the function returns
}).then(() => {
  console.log('Lock released');
});

// Request a shared lock
navigator.locks.request('shared_resource', { mode: 'shared' }, async (lock) => {
  // Multiple shared locks can be held simultaneously
  console.log(`Shared lock acquired: ${lock.name}`);
}).then(() => {
  console.log('Shared lock released');
});
copy

詳細的 API 說明文件請參見 worker_threads.locks。

navigator.platform#

• 類型：<string>

navigator.platform 唯讀屬性會回傳一個字串，識別 Node.js 實例正在運行的平台。

console.log(`This process is running on ${navigator.platform}`);
copy

navigator.userAgent#

• 類型：<string>

navigator.userAgent 唯讀屬性會回傳由執行階段名稱和主要版本號組成的使用者代理 (User Agent)。

console.log(`The user-agent is ${navigator.userAgent}`); // Prints "Node.js/21"
copy

performance#

perf_hooks.performance 物件。

類別：PerformanceEntry#

PerformanceEntry 類別。有關更多詳細資訊，請參見 PerformanceEntry。

類別：PerformanceMark#

PerformanceMark 類別。有關更多詳細資訊，請參見 PerformanceMark。

類別：PerformanceMeasure#

PerformanceMeasure 類別。有關更多詳細資訊，請參見 PerformanceMeasure。

類別：PerformanceObserver#

PerformanceObserver 類別。有關更多詳細資訊，請參見 PerformanceObserver。

類別：PerformanceObserverEntryList#

PerformanceObserverEntryList 類別。有關更多詳細資訊，請參見 PerformanceObserverEntryList。

類別：PerformanceResourceTiming#

PerformanceResourceTiming 類別。有關更多詳細資訊，請參見 PerformanceResourceTiming。

process#

• 類型：<Object>

process 物件。請參見 process 物件 章節。

queueMicrotask(callback)#

• callback <Function> 要排入佇列的函式。

queueMicrotask() 方法會將微任務 (microtask) 排入佇列以調用 callback。如果 callback 拋出異常，將會發出 process 物件 的 'uncaughtException' 事件。

微任務佇列由 V8 管理，其用法與 Node.js 管理的 process.nextTick() 佇列類似。在 Node.js 事件迴圈的每一輪中，process.nextTick() 佇列總是先於微任務佇列處理。

// Here, `queueMicrotask()` is used to ensure the 'load' event is always
// emitted asynchronously, and therefore consistently. Using
// `process.nextTick()` here would result in the 'load' event always emitting
// before any other promise jobs.

DataHandler.prototype.load = async function load(key) {
  const hit = this._cache.get(key);
  if (hit !== undefined) {
    queueMicrotask(() => {
      this.emit('load', hit);
    });
    return;
  }

  const data = await fetchData(key);
  this._cache.set(key, data);
  this.emit('load', data);
};
copy

類別：QuotaExceededError#

WHATWG {QuotaExceededError} 類別。繼承自 <DOMException>。

類別：ReadableByteStreamController#

瀏覽器相容的 ReadableByteStreamController 實作。

類別：ReadableStream#

瀏覽器相容的 ReadableStream 實作。

類別：ReadableStreamBYOBReader#

瀏覽器相容的 ReadableStreamBYOBReader 實作。

類別：ReadableStreamBYOBRequest#

瀏覽器相容的 ReadableStreamBYOBRequest 實作。

類別：ReadableStreamDefaultController#

瀏覽器相容的 ReadableStreamDefaultController 實作。

類別：ReadableStreamDefaultReader#

瀏覽器相容的 ReadableStreamDefaultReader 實作。

類別：Request#

瀏覽器相容的 <Request> 實作。

require()#

此變數看起來像是全域的，但實際上並非如此。請參見 require()。

類別：Response#

瀏覽器相容的 <Response> 實作。

sessionStorage#

瀏覽器相容的 sessionStorage 實作。數據儲存在記憶體中，儲存配額為 10 MB。sessionStorage 數據僅保存在目前運行的程序中，且不會在 worker 之間共享。

setImmediate(callback[, ...args])#

setImmediate 已在 timers (計時器) 章節中說明。

setInterval(callback, delay[, ...args])#

setInterval 已在 timers (計時器) 章節中說明。

setTimeout(callback, delay[, ...args])#

setTimeout 已在 timers (計時器) 章節中說明。

類別：Storage#

瀏覽器相容的 <Storage> 實作。

structuredClone(value[, options])#

WHATWG structuredClone 方法。

類別：SubtleCrypto#

瀏覽器相容的 <SubtleCrypto> 實作。此全域變數僅在 Node.js 二進位檔編譯時包含 node:crypto 模組支援的情況下才可用。

類別：TextDecoder#

WHATWG TextDecoder 類別。請參見 TextDecoder 章節。

類別：TextDecoderStream#

瀏覽器相容的 TextDecoderStream 實作。

類別：TextEncoder#

WHATWG TextEncoder 類別。請參見 TextEncoder 章節。

類別：TextEncoderStream#

瀏覽器相容的 TextEncoderStream 實作。

類別：TransformStream#

瀏覽器相容的 TransformStream 實作。

類別：TransformStreamDefaultController#

瀏覽器相容的 TransformStreamDefaultController 實作。

類別：URL#

WHATWG URL 類別。請參見 URL 章節。

類別：URLPattern#

WHATWG URLPattern 類別。請參見 URLPattern 章節。

類別：URLSearchParams#

WHATWG URLSearchParams 類別。請參見 URLSearchParams 章節。

類別：WebAssembly#

• 類型：<Object>

作為所有 W3C WebAssembly 相關功能的命名空間物件。有關用法和相容性，請參見 Mozilla 開發者網路 (MDN)。

類別：WebSocket#

瀏覽器相容的 <WebSocket> 實作。使用 --no-experimental-websocket CLI 旗標可停用此 API。

類別：WritableStream#

瀏覽器相容的 WritableStream 實作。

類別：WritableStreamDefaultController#

瀏覽器相容的 WritableStreamDefaultController 實作。

類別：WritableStreamDefaultWriter#

瀏覽器相容的 WritableStreamDefaultWriter 實作。