deprecation 弃用


  • 该 API 的使用是不安全的。

  • 改进的替代 API 可用。

  • 预计在未来的主要版本中会对 API 进行重大更改。

  • 仅文档

  • 运行时

  • 生命结束

仅文档弃用是仅在 Node.js API 文档中表达的弃用。 这些在运行 Node.js 时不会产生副作用。 某些仅文档的弃用在使用 --pending-deprecation 标志(或其替代的 NODE_PENDING_DEPRECATION=1 环境变量)启动时会触发运行时警告,类似于下面的运行时弃用。 支持该标志的仅文档弃用已在弃用的 API 列表 中明确标记。

默认情况下,运行时弃用将生成进程警告,该警告将在第一次使用弃用的 API 时打印到 stderr。 当使用 --throw-deprecation 命令行标志时,运行时弃用将导致抛出错误。

当特性已经或即将从 Node.js 中删除时,使用生命结束的弃用。

Node.js may deprecate APIs for any of the following reasons:

  • Use of the API is unsafe.
  • An improved alternative API is available.
  • Breaking changes to the API are expected in a future major release.

Node.js utilizes three kinds of Deprecations:

  • Documentation-only
  • Runtime
  • End-of-Life

A Documentation-only deprecation is one that is expressed only within the Node.js API docs. These generate no side-effects while running Node.js. Some Documentation-only deprecations trigger a runtime warning when launched with --pending-deprecation flag (or its alternative, NODE_PENDING_DEPRECATION=1 environment variable), similarly to Runtime deprecations below. Documentation-only deprecations that support that flag are explicitly labeled as such in the list of Deprecated APIs.

A Runtime deprecation will, by default, generate a process warning that will be printed to stderr the first time the deprecated API is used. When the --throw-deprecation command-line flag is used, a Runtime deprecation will cause an error to be thrown.

An End-of-Life deprecation is used when functionality is or will soon be removed from Node.js.