Node.js v22.21.0 文档

类：AbortController#>

¥Class: AbortController

用于在选定的基于 Promise 的 API 中触发取消信号的实用工具类。该 API 基于 Web API <AbortController>。

¥A utility class used to signal cancelation in selected Promise-based APIs. The API is based on the 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 拷贝

abortController.abort([reason])#>

• reason <any> 可选的原因，可在 AbortSignal 的 reason 属性中检索。

  ¥reason <any> An optional reason, retrievable on the AbortSignal's reason property.

触发中止信号，使 abortController.signal 触发 'abort' 事件。

¥Triggers the abort signal, causing the abortController.signal to emit the 'abort' event.

abortController.signal#>

• 类型：<AbortSignal>

  ¥Type: <AbortSignal>

类：AbortSignal#>

¥Class: AbortSignal

• 继承：<EventTarget>

  ¥Extends: <EventTarget>

AbortSignal 用于在调用 abortController.abort() 方法时通知监视器。

¥The AbortSignal is used to notify observers when the abortController.abort() method is called.

静态方法：AbortSignal.abort([reason])#>

¥Static method: AbortSignal.abort([reason])

• reason <any>

• 返回：<AbortSignal>

  ¥Returns: <AbortSignal>

返回新的已中止的 AbortSignal。

¥Returns a new already aborted AbortSignal.

静态方法：AbortSignal.timeout(delay)#>

¥Static method: AbortSignal.timeout(delay)

• delay <number> 触发 AbortSignal 之前等待的毫秒数。

  ¥delay <number> The number of milliseconds to wait before triggering the AbortSignal.

返回新的 AbortSignal，其将在 delay 毫秒内中止。

¥Returns a new AbortSignal which will be aborted in delay milliseconds.

静态方法：AbortSignal.any(signals)#>

¥Static method: AbortSignal.any(signals)

• signals <AbortSignal[]> 其中的 AbortSignal 组成了新的 AbortSignal。

  ¥signals <AbortSignal[]> The AbortSignals of which to compose a new AbortSignal.

返回一个新的 AbortSignal，如果任何提供的信号被中止，它将被中止。它的 abortSignal.reason 将设置为导致它中止的 signals 中的任何一个。

¥Returns a new AbortSignal which will be aborted if any of the provided signals are aborted. Its abortSignal.reason will be set to whichever one of the signals caused it to be aborted.

事件：'abort'#>

¥Event: 'abort'

当调用 abortController.abort() 方法时，则触发 'abort' 事件。使用单个对象参数调用回调，该对象具有被设置为 'abort' 的 type 属性：

¥The 'abort' event is emitted when the abortController.abort() method is called. The callback is invoked with a single object argument with a single type property set to '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(); 拷贝

与 AbortSignal 关联的 AbortController 只会触发一次 'abort' 事件。建议在添加 'abort' 事件监听器之前代码检查 abortSignal.aborted 属性是否为 false。

¥The AbortController with which the AbortSignal is associated will only ever trigger the 'abort' event once. We recommended that code check that the abortSignal.aborted attribute is false before adding an 'abort' event listener.

任何绑定到 AbortSignal 的事件监听器都应使用 { once: true } 选项（或者，如果使用 EventEmitter API 绑定监听器，则使用 once() 方法）以确保在处理 'abort' 事件后立即删除事件监听器。不这样做可能会导致内存泄漏。

¥Any event listeners attached to the AbortSignal should use the { once: true } option (or, if using the EventEmitter APIs to attach a listener, use the once() method) to ensure that the event listener is removed as soon as the 'abort' event is handled. Failure to do so may result in memory leaks.

abortSignal.aborted#>

• 类型：<boolean> 中止 AbortController 后为真。

  ¥Type: <boolean> True after the AbortController has been aborted.

abortSignal.onabort#>

• 类型：<Function>

  ¥Type: <Function>

可选的回调函数，可以由用户代码设置，以便当调用 abortController.abort() 函数时得到通知。

¥An optional callback function that may be set by user code to be notified when the abortController.abort() function has been called.

abortSignal.reason#>

• 类型：<any>

  ¥Type: <any>

当触发 AbortSignal 时指定的可选的原因。

¥An optional reason specified when the AbortSignal was triggered.

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

abortSignal.throwIfAborted()#>

如果 abortSignal.aborted 是 true，则抛出 abortSignal.reason。

¥If abortSignal.aborted is true, throws abortSignal.reason.

类：Blob#>

¥Class: Blob

参见 <Blob>。

¥See <Blob>.

类：Buffer#>

¥Class: Buffer

• 类型：<Function>

  ¥Type: <Function>

用于处理二进制数据。参见 缓冲区。

¥Used to handle binary data. See the buffer section.

类：ByteLengthQueuingStrategy#>

¥Class: ByteLengthQueuingStrategy

ByteLengthQueuingStrategy 的浏览器兼容实现。

¥A browser-compatible implementation of ByteLengthQueuingStrategy.

__dirname#>

此变量可能看起来是全局的，但实际上不是。参见 __dirname。

¥This variable may appear to be global but is not. See __dirname.

__filename#>

此变量可能看起来是全局的，但实际上不是。参见 __filename。

¥This variable may appear to be global but is not. See __filename.

atob(data)#>

buffer.atob() 的全局别名。

¥Global alias for buffer.atob().

类：BroadcastChannel#>

¥Class: BroadcastChannel

参见 <BroadcastChannel>。

¥See <BroadcastChannel>.

btoa(data)#>

buffer.btoa() 的全局别名。

¥Global alias for buffer.btoa().

clearImmediate(immediateObject)#>

clearImmediate 在 定时器 部分中描述。

¥clearImmediate is described in the timers section.

clearInterval(intervalObject)#>

clearInterval 在 定时器 部分中描述。

¥clearInterval is described in the timers section.

clearTimeout(timeoutObject)#>

clearTimeout 在 定时器 部分中描述。

¥clearTimeout is described in the timers section.

类：CompressionStream#>

¥Class: CompressionStream

CompressionStream 的浏览器兼容实现。

¥A browser-compatible implementation of CompressionStream.

console#>

• 类型：<Object>

  ¥Type: <Object>

用于打印到标准输出和标准错误。参阅 console 章节。

¥Used to print to stdout and stderr. See the console section.

类：CountQueuingStrategy#>

¥Class: CountQueuingStrategy

CountQueuingStrategy 的浏览器兼容实现。

¥A browser-compatible implementation of CountQueuingStrategy.

类：Crypto#>

¥Class: Crypto

<Crypto> 的浏览器兼容实现。只有在编译 Node.js 二进制文件时包含对 node:crypto 模块的支持，此全局才可用。

¥A browser-compatible implementation of <Crypto>. This global is available only if the Node.js binary was compiled with including support for the node:crypto module.

crypto#>

网络加密 API 的浏览器兼容实现。

¥A browser-compatible implementation of the Web Crypto API.

类：CryptoKey#>

¥Class: CryptoKey

<CryptoKey> 的浏览器兼容实现。只有在编译 Node.js 二进制文件时包含对 node:crypto 模块的支持，此全局才可用。

¥A browser-compatible implementation of <CryptoKey>. This global is available only if the Node.js binary was compiled with including support for the node:crypto module.

类：CustomEvent#>

¥Class: CustomEvent

<CustomEvent> 的浏览器兼容实现。

¥A browser-compatible implementation of <CustomEvent>.

类：DecompressionStream#>

¥Class: DecompressionStream

DecompressionStream 的浏览器兼容实现。

¥A browser-compatible implementation of DecompressionStream.

类：Event#>

¥Class: Event

Event 类的浏览器兼容的实现。有关详细信息，请参阅 EventTarget 和 Event API。

¥A browser-compatible implementation of the Event class. See EventTarget and Event API for more details.

类：EventSource#>

¥Class: EventSource

EventSource 的浏览器兼容实现。

¥A browser-compatible implementation of EventSource.

类：EventTarget#>

¥Class: EventTarget

EventTarget 类的浏览器兼容的实现。有关详细信息，请参阅 EventTarget 和 Event API。

¥A browser-compatible implementation of the EventTarget class. See EventTarget and Event API for more details.

exports#>

此变量可能看起来是全局的，但实际上不是。参见 exports。

¥This variable may appear to be global but is not. See exports.

fetch#>

fetch() 函数的浏览器兼容实现。

¥A browser-compatible implementation of the fetch() function.

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

该实现基于 undici，这是一个为 Node.js 从头编写的 HTTP/1.1 客户端。你可以通过读取 process.versions.undici 属性来确定 Node.js 进程中打包了哪个版本的 undici。

¥The implementation is based upon undici, an HTTP/1.1 client written from scratch for Node.js. You can figure out which version of undici is bundled in your Node.js process reading the process.versions.undici property.

自定义调度程序#>

¥Custom dispatcher

你可以使用自定义调度程序来调度在 fetch 的选项对象中传递它的请求。调度程序必须与 undici 的 Dispatcher 类 兼容。

¥You can use a custom dispatcher to dispatch requests passing it in fetch's options object. The dispatcher must be compatible with undici's Dispatcher class.

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

可以通过安装 undici 并使用 setGlobalDispatcher() 方法来更改 Node.js 中的全局调度程序。调用此方法将同时影响 undici 和 Node.js。

¥It is possible to change the global dispatcher in Node.js by installing undici and using the setGlobalDispatcher() method. Calling this method will affect both undici and Node.js.

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

相关类#>

¥Related classes

以下全局变量可用于 fetch：

¥The following globals are available to use with fetch:

• FormData

• Headers

• Request

• Response。

类：File#>

¥Class: File

参见 <File>。

¥See <File>.

类：FormData#>

¥Class: FormData

<FormData> 的浏览器兼容实现。

¥A browser-compatible implementation of <FormData>.

global#>

• 类型：<Object> 全局命名空间对象。

  ¥Type: <Object> The global namespace object.

在浏览器中，顶层作用域传统上是全局作用域。这意味着 var something 将定义一个新的全局变量，ECMAScript 模块除外。在 Node.js 中，这是不同的。顶层作用域不是全局作用域；Node.js 模块内的 var something 对于该模块而言是本地的，无论它是 CommonJS 模块 还是 ECMAScript 模块。

¥In browsers, the top-level scope has traditionally been the global scope. This means that var something will define a new global variable, except within ECMAScript modules. In Node.js, this is different. The top-level scope is not the global scope; var something inside a Node.js module will be local to that module, regardless of whether it is a CommonJS module or an ECMAScript module.

类：Headers#>

¥Class: Headers

<Headers> 的浏览器兼容实现。

¥A browser-compatible implementation of <Headers>.

localStorage#>

localStorage 的浏览器兼容实现。数据以未加密的形式存储在 --localstorage-file CLI 标志指定的文件中。可存储的最大数据量为 10 MB。不支持在 Web Storage API 之外修改此数据。使用 --experimental-webstorage CLI 标志启用此 API。在服务器上下文中使用时，localStorage 数据不是按用户或按请求存储的，而是在所有用户和请求之间共享。

¥A browser-compatible implementation of localStorage. Data is stored unencrypted in the file specified by the --localstorage-file CLI flag. The maximum amount of data that can be stored is 10 MB. Any modification of this data outside of the Web Storage API is not supported. Enable this API with the --experimental-webstorage CLI flag. localStorage data is not stored per user or per request when used in the context of a server, it is shared across all users and requests.

类：MessageChannel#>

¥Class: MessageChannel

MessageChannel 类。有关详细信息，请参阅 MessageChannel。

¥The MessageChannel class. See MessageChannel for more details.

类：MessageEvent#>

¥Class: MessageEvent

MessageEvent 的浏览器兼容实现。

¥A browser-compatible implementation of MessageEvent.

类：MessagePort#>

¥Class: MessagePort

MessagePort 类。有关详细信息，请参阅 MessagePort。

¥The MessagePort class. See MessagePort for more details.

module#>

此变量可能看起来是全局的，但实际上不是。参见 module。

¥This variable may appear to be global but is not. See module.

类：Navigator#>

¥Class: Navigator

导航器 API 的部分实现。

¥A partial implementation of the Navigator API.

navigator#>

window.navigator 的部分实现。

¥A partial implementation of window.navigator.

navigator.hardwareConcurrency#>

• 类型：<number>

  ¥Type: <number>

navigator.hardwareConcurrency 只读属性返回当前 Node.js 实例可用的逻辑处理器数量。

¥The navigator.hardwareConcurrency read-only property returns the number of logical processors available to the current Node.js instance.

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

navigator.language#>

• 类型：<string>

  ¥Type: <string>

navigator.language 只读属性返回一个表示 Node.js 实例的首选语言的字符串。语言将由 Node.js 在运行时使用的 ICU 库根据操作系统的默认语言来确定。

¥The navigator.language read-only property returns a string representing the preferred language of the Node.js instance. The language will be determined by the ICU library used by Node.js at runtime based on the default language of the operating system.

该值代表 RFC 5646 中定义的语言版本。

¥The value is representing the language version as defined in RFC 5646.

没有 ICU 的构建的后备值是 'en-US'。

¥The fallback value on builds without ICU is 'en-US'.

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

navigator.languages#>

• 类型：{Array}

  ¥Type: {Array}

navigator.languages 只读属性返回一个字符串数组，表示 Node.js 实例的首选语言。默认情况下，navigator.languages 只包含 navigator.language 的值，该值将由 Node.js 在运行时使用的 ICU 库根据操作系统的默认语言确定。

¥The navigator.languages read-only property returns an array of strings representing the preferred languages of the Node.js instance. By default navigator.languages contains only the value of navigator.language, which will be determined by the ICU library used by Node.js at runtime based on the default language of the operating system.

没有 ICU 的构建的后备值是 ['en-US']。

¥The fallback value on builds without ICU is ['en-US'].

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

navigator.platform#>

• 类型：<string>

  ¥Type: <string>

navigator.platform 只读属性返回一个字符串，标识 Node.js 实例运行的平台。

¥The navigator.platform read-only property returns a string identifying the platform on which the Node.js instance is running.

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

navigator.userAgent#>

• 类型：<string>

  ¥Type: <string>

navigator.userAgent 只读属性返回由运行时名称和主版本号组成的用户代理。

¥The navigator.userAgent read-only property returns user agent consisting of the runtime name and major version number.

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

类：PerformanceEntry#>

¥Class: PerformanceEntry

PerformanceEntry 类。有关详细信息，请参阅 PerformanceEntry。

¥The PerformanceEntry class. See PerformanceEntry for more details.

类：PerformanceMark#>

¥Class: PerformanceMark

PerformanceMark 类。有关详细信息，请参阅 PerformanceMark。

¥The PerformanceMark class. See PerformanceMark for more details.

类：PerformanceMeasure#>

¥Class: PerformanceMeasure

PerformanceMeasure 类。有关详细信息，请参阅 PerformanceMeasure。

¥The PerformanceMeasure class. See PerformanceMeasure for more details.

类：PerformanceObserver#>

¥Class: PerformanceObserver

PerformanceObserver 类。有关详细信息，请参阅 PerformanceObserver。

¥The PerformanceObserver class. See PerformanceObserver for more details.

类：PerformanceObserverEntryList#>

¥Class: PerformanceObserverEntryList

PerformanceObserverEntryList 类。有关详细信息，请参阅 PerformanceObserverEntryList。

¥The PerformanceObserverEntryList class. See PerformanceObserverEntryList for more details.

类：PerformanceResourceTiming#>

¥Class: PerformanceResourceTiming

PerformanceResourceTiming 类。有关详细信息，请参阅 PerformanceResourceTiming。

¥The PerformanceResourceTiming class. See PerformanceResourceTiming for more details.

performance#>

perf_hooks.performance 对象。

¥The perf_hooks.performance object.

process#>

• 类型：<Object>

  ¥Type: <Object>

进程对象。参阅 process 对象 章节。

¥The process object. See the process object section.

queueMicrotask(callback)#>

• callback <Function> 要排队的函数。

  ¥callback <Function> Function to be queued.

queueMicrotask() 方法将微任务排队以调用 callback。如果 callback 抛出异常，将触发 process 对象 'uncaughtException' 事件。

¥The queueMicrotask() method queues a microtask to invoke callback. If callback throws an exception, the process object 'uncaughtException' event will be emitted.

微任务队列由 V8 管理，并且可以以类似于 process.nextTick() 队列的方式使用，后者由 Node.js 管理。在 Node.js 事件循环的每次轮询中，process.nextTick() 队列总是在微任务队列之前处理。

¥The microtask queue is managed by V8 and may be used in a similar manner to the process.nextTick() queue, which is managed by Node.js. The process.nextTick() queue is always processed before the microtask queue within each turn of the Node.js event loop.

// 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);
}; 拷贝

类：ReadableByteStreamController#>

¥Class: ReadableByteStreamController

ReadableByteStreamController 的浏览器兼容实现。

¥A browser-compatible implementation of ReadableByteStreamController.

类：ReadableStream#>

¥Class: ReadableStream

ReadableStream 的浏览器兼容实现。

¥A browser-compatible implementation of ReadableStream.

类：ReadableStreamBYOBReader#>

¥Class: ReadableStreamBYOBReader

ReadableStreamBYOBReader 的浏览器兼容实现。

¥A browser-compatible implementation of ReadableStreamBYOBReader.

类：ReadableStreamBYOBRequest#>

¥Class: ReadableStreamBYOBRequest

ReadableStreamBYOBRequest 的浏览器兼容实现。

¥A browser-compatible implementation of ReadableStreamBYOBRequest.

类：ReadableStreamDefaultController#>

¥Class: ReadableStreamDefaultController

ReadableStreamDefaultController 的浏览器兼容实现。

¥A browser-compatible implementation of ReadableStreamDefaultController.

类：ReadableStreamDefaultReader#>

¥Class: ReadableStreamDefaultReader

ReadableStreamDefaultReader 的浏览器兼容实现。

¥A browser-compatible implementation of ReadableStreamDefaultReader.

require()#>

此变量可能看起来是全局的，但实际上不是。参见 require()。

¥This variable may appear to be global but is not. See require().

类：Response#>

¥Class: Response

<Response> 的浏览器兼容实现。

¥A browser-compatible implementation of <Response>.

类：Request#>

¥Class: Request

<Request> 的浏览器兼容实现。

¥A browser-compatible implementation of <Request>.

sessionStorage#>

sessionStorage 的浏览器兼容实现。数据存储在内存中，存储配额为 10 MB。sessionStorage 数据仅在当前正在运行的进程中保留，不会在工作进程之间共享。

¥A browser-compatible implementation of sessionStorage. Data is stored in memory, with a storage quota of 10 MB. sessionStorage data persists only within the currently running process, and is not shared between workers.

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

setImmediate 在 定时器 部分中描述。

¥setImmediate is described in the timers section.

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

setInterval 在 定时器 部分中描述。

¥setInterval is described in the timers section.

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

setTimeout 在 定时器 部分中描述。

¥setTimeout is described in the timers section.

类：Storage#>

¥Class: Storage

Storage 的浏览器兼容实现。

¥A browser-compatible implementation of Storage.

structuredClone(value[, options])#>

WHATWG structuredClone 方法。

¥The WHATWG structuredClone method.

类：SubtleCrypto#>

¥Class: SubtleCrypto

<SubtleCrypto> 的浏览器兼容实现。只有在编译 Node.js 二进制文件时包含对 node:crypto 模块的支持，此全局才可用。

¥A browser-compatible implementation of <SubtleCrypto>. This global is available only if the Node.js binary was compiled with including support for the node:crypto module.

类：DOMException#>

¥Class: DOMException

WHATWG DOMException 类。

¥The WHATWG DOMException class.

类：TextDecoder#>

¥Class: TextDecoder

WHATWG TextDecoder 类。参阅 TextDecoder 章节。

¥The WHATWG TextDecoder class. See the TextDecoder section.

类：TextDecoderStream#>

¥Class: TextDecoderStream

TextDecoderStream 的浏览器兼容实现。

¥A browser-compatible implementation of TextDecoderStream.

类：TextEncoder#>

¥Class: TextEncoder

WHATWG TextEncoder 类。参阅 TextEncoder 章节。

¥The WHATWG TextEncoder class. See the TextEncoder section.

类：TextEncoderStream#>

¥Class: TextEncoderStream

TextEncoderStream 的浏览器兼容实现。

¥A browser-compatible implementation of TextEncoderStream.

类：TransformStream#>

¥Class: TransformStream

TransformStream 的浏览器兼容实现。

¥A browser-compatible implementation of TransformStream.

类：TransformStreamDefaultController#>

¥Class: TransformStreamDefaultController

TransformStreamDefaultController 的浏览器兼容实现。

¥A browser-compatible implementation of TransformStreamDefaultController.

类：URL#>

¥Class: URL

WHATWG URL 类。参阅 URL 章节。

¥The WHATWG URL class. See the URL section.

类：URLSearchParams#>

¥Class: URLSearchParams

WHATWG URLSearchParams 类。参阅 URLSearchParams 章节。

¥The WHATWG URLSearchParams class. See the URLSearchParams section.

类：WebAssembly#>

¥Class: WebAssembly

• 类型：<Object>

  ¥Type: <Object>

充当所有 W3C WebAssembly 相关功能的名称空间的对象。有关用法和兼容性，请参阅 Mozilla 开发者网络。

¥The object that acts as the namespace for all W3C WebAssembly related functionality. See the Mozilla Developer Network for usage and compatibility.

类：WebSocket#>

¥Class: WebSocket

WebSocket 的浏览器兼容实现。使用 --no-experimental-websocket CLI 标志禁用此 API。

¥A browser-compatible implementation of WebSocket. Disable this API with the --no-experimental-websocket CLI flag.

类：WritableStream#>

¥Class: WritableStream

WritableStream 的浏览器兼容实现。

¥A browser-compatible implementation of WritableStream.

类：WritableStreamDefaultController#>

¥Class: WritableStreamDefaultController

WritableStreamDefaultController 的浏览器兼容实现。

¥A browser-compatible implementation of WritableStreamDefaultController.

类：WritableStreamDefaultWriter#>

¥Class: WritableStreamDefaultWriter

WritableStreamDefaultWriter 的浏览器兼容实现。

¥A browser-compatible implementation of WritableStreamDefaultWriter.