Node.js v20.11.0 文档


About this documentation

欢迎使用 Node.js 的官方 API 参考文档!

Welcome to the official API reference documentation for Node.js!

Node.js 是基于 V8 JavaScript 引擎 构建的 JavaScript 运行时。

Node.js is a JavaScript runtime built on the V8 JavaScript engine.



问题追踪器 中报告本文档中的错误。有关如何提交拉取请求的说明,请参阅 贡献指南

Report errors in this documentation in the issue tracker. See the contributing guide for directions on how to submit pull requests.


Stability index

在文档中都有章节稳定性的标志。有些 API 已被证明和依赖,因此它们几乎不可能改变。有些则是全新的和实验的、或者已知是危险的。

Throughout the documentation are indications of a section's stability. Some APIs are so proven and so relied upon that they are unlikely to ever change at all. Others are brand new and experimental, or known to be hazardous.


The stability indices are as follows:

稳定性: 0 - 已弃用。该功能可能会触发警告。不保证向后兼容性。

Stability: 0 - Deprecated. The feature may emit warnings. Backward compatibility is not guaranteed.

稳定性: 1 - 实验性的。该功能不受 语义版本控制 规则的约束。任何未来版本中都可能发生非向后兼容的更改或删除。不建议在生产环境中使用该功能。

Stability: 1 - Experimental. The feature is not subject to semantic versioning rules. Non-backward compatible changes or removal may occur in any future release. Use of the feature is not recommended in production environments.


Experimental features are subdivided into stages:

  • 1.0 - 早期开发。此阶段的实验功能尚未完成,可能会发生重大变化。

    1.0 - Early development. Experimental features at this stage are unfinished and subject to substantial change.

  • 1.1 - 积极开发。此阶段的实验功能已接近最低可行性。

    1.1 - Active development. Experimental features at this stage are nearing minimum viability.

  • 1.2 - 发布候选。此阶段的实验功能有望变得稳定。预计不会有进一步的重大更改,但可能仍会根据用户反馈进行更改。我们鼓励用户测试和反馈,以便我们可以知道此功能已准备好标记为稳定。

    1.2 - Release candidate. Experimental features at this stage are hopefully ready to become stable. No further breaking changes are anticipated but may still occur in response to user feedback. We encourage user testing and feedback so that we can know that this feature is ready to be marked as stable.

稳定性: 2 - 稳定的。与 npm 生态系统的兼容性是重中之重。

Stability: 2 - Stable. Compatibility with the npm ecosystem is a high priority.

稳定性: 3 - 旧版的。尽管此功能不太可能被删除并且仍受语义版本控制保证的保护,但它不再被积极维护,并且有其他替代方案可用。

Stability: 3 - Legacy. Although this feature is unlikely to be removed and is still covered by semantic versioning guarantees, it is no longer actively maintained, and other alternatives are available.

如果特性的使用没有害处并且其在 npm 生态系统中被广泛依赖,则标记为旧版而不是弃用。旧版特性中发现的缺陷不太可能被修复。

Features are marked as legacy rather than being deprecated if their use does no harm, and they are widely relied upon within the npm ecosystem. Bugs found in legacy features are unlikely to be fixed.

使用实验性功能时要小心,特别是在编写库时。用户可能不知道正在使用实验的特性。当实验的 API 发生修改时,故障或行为的变化可能会让用户感到诧异。为避免诧异,使用实验的特性可能需要命令行标志。实验性功能也可能会触发 警告

Use caution when making use of Experimental features, particularly when authoring libraries. Users may not be aware that experimental features are being used. Bugs or behavior changes may surprise users when Experimental API modifications occur. To avoid surprises, use of an Experimental feature may need a command-line flag. Experimental features may also emit a warning.


Stability overview

assert(2) 稳定
async_context(2) 稳定
async_hooks(1) 实验
buffer(2) 稳定
child_process(2) 稳定
cluster(2) 稳定
console(2) 稳定
corepack(1) 实验
crypto(2) 稳定
debugger(2) 稳定
dgram(2) 稳定
diagnostics_channel(2) 稳定
dns(2) 稳定
domain(0) 弃用
events(2) 稳定
fs(2) 稳定
http(2) 稳定
http2(2) 稳定
https(2) 稳定
inspector(2) 稳定
modules(2) 稳定
n-api(2) 稳定
net(2) 稳定
os(2) 稳定
path(2) 稳定
perf_hooks(2) 稳定
policy(1) 实验
punycode(0) 弃用
querystring(2) 稳定
readline(2) 稳定
repl(2) 稳定
report(2) 稳定
single-executable-applications(1) 实验
stream(2) 稳定
string_decoder(2) 稳定
test(2) 稳定
timers(2) 稳定
tls(2) 稳定
tracing(1) 实验
tty(2) 稳定
url(2) 稳定
util(2) 稳定
vm(2) 稳定
wasi(1) 实验
webstreams(1) 实验
worker_threads(2) 稳定
zlib(2) 稳定

JSON 输出#

JSON output

每个 .html 文档都有对应的 .json 文档。这适用于使用该文档的 IDE 和其他实用工具。

Every .html document has a corresponding .json document. This is for IDEs and other utilities that consume the documentation.


System calls and man pages

封装系统调用的 Node.js 函数会在文档中描述。文档链接到对应的描述该系统调用的工作方式的帮助手册。

Node.js functions which wrap a system call will document that. The docs link to the corresponding man pages which describe how the system call works.

大多数 Unix 系统调用都有 Windows 类似物。尽管如此,行为的差异可能是不可避免的。

Most Unix system calls have Windows analogues. Still, behavior differences may be unavoidable.