已弃用的 API

Node.js API 可能因以下任何原因而被弃用：

• 使用该 API 不安全。
• 有改进的替代 API 可用。
• 预计在未来的主要版本中会对 API 进行破坏性更改。

Node.js 使用四种弃用方式：

• 仅文档
• 应用程序（仅限非 node_modules 代码）
• 运行时（所有代码）
• 生命周期结束

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

默认情况下，仅针对非 node_modules 代码的应用程序弃用会在首次于非 node_modules 加载的代码中使用弃用 API 时生成一个进程警告并打印到 stderr。当使用 --throw-deprecation 命令行标志时，运行时弃用将导致抛出错误。当使用 --pending-deprecation 时，警告也会为从 node_modules 加载的代码发出。

所有代码的运行时弃用类似于非 node_modules 代码的运行时弃用，不同之处在于它也会为从 node_modules 加载的代码发出警告。

当功能正在或即将从 Node.js 中移除时，会使用生命周期结束弃用。

偶尔，API 的弃用可能会被撤销。在这种情况下，本文档将更新与决策相关的信息。但是，弃用标识符不会被修改。

OutgoingMessage.prototype.flush() 已被移除。请改用 OutgoingMessage.prototype.flushHeaders()。

_linklist 模块已弃用。请使用用户空间的替代方案。

_writableState.buffer 已被移除。请改用 _writableState.getBuffer()。

CryptoStream.prototype.readyState 属性已被移除。

Buffer() 函数和 new Buffer() 构造函数因 API 可用性问题可能导致意外的安全问题而被弃用。

作为替代，请使用以下构造 Buffer 对象的方法之一：

• Buffer.alloc(size[, fill[, encoding]])：创建具有_已初始化_内存的 Buffer。
• Buffer.allocUnsafe(size)：创建具有_未初始化_内存的 Buffer。
• Buffer.allocUnsafeSlow(size)：创建具有_未初始化_内存的 Buffer。
• Buffer.from(array)：创建具有 array 副本的 Buffer
• Buffer.from(arrayBuffer[, byteOffset[, length]]) - 创建包装给定 arrayBuffer 的 Buffer。
• Buffer.from(buffer)：创建复制 buffer 的 Buffer。
• Buffer.from(string[, encoding])：创建复制 string 的 Buffer。

如果没有 --pending-deprecation，运行时警告仅发生在不在 node_modules 中的代码。这意味着依赖项中的 Buffer() 用法不会有弃用警告。使用 --pending-deprecation 时，无论 Buffer() 用法出现在何处，都会产生运行时警告。

在 child_process 模块的 spawn()、fork() 和 exec() 方法中，options.customFds 选项已弃用。应改用 options.stdio 选项。

在早期版本的 Node.js cluster 中，一个名为 suicide 的布尔属性被添加到 Worker 对象。该属性的目的是指示 Worker 实例如何以及为何退出。在 Node.js 6.0.0 中，旧属性被弃用并替换为新的 worker.exitedAfterDisconnect 属性。旧属性名称并未精确描述实际语义，且带有不必要的情感色彩。

类型：仅文档

node:constants 模块已弃用。当需要访问与特定 Node.js 内置模块相关的常量时，开发者应参考相关模块暴露的 constants 属性。例如，require('node:fs').constants 和 require('node:os').constants。

在 Node.js 6.0 中，未指定 digest 使用 crypto.pbkdf2() API 已被弃用，因为该方法默认使用不推荐的 'SHA1' digest。此前，会打印弃用警告。从 Node.js 8.0.0 开始，使用 digest 设置为 undefined 调用 crypto.pbkdf2() 或 crypto.pbkdf2Sync() 将抛出 TypeError。

从 Node.js 11.0.0 开始，使用 digest 设置为 null 调用这些函数将打印弃用警告，以与 digest 为 undefined 时的行为保持一致。

但现在，传递 undefined 或 null 都将抛出 TypeError。

crypto.createCredentials() API 已被移除。请改用 tls.createSecureContext()。

crypto.Credentials 类已被移除。请改用 tls.SecureContext。

Domain.dispose() 已被移除。请改为通过设置在域上的错误事件处理程序显式地从失败的 I/O 操作恢复。

从 Node.js 10.0.0 开始，调用不带回调的异步函数会抛出 TypeError。参见 https://github.com/nodejs/node/pull/12562。

fs.read() 的遗留 String 接口已弃用。请改用文档中提到的 Buffer API。

fs.readSync() 遗留 String 接口已弃用。请改用文档中提到的 Buffer API。

global 属性的 GLOBAL 和 root 别名在 Node.js 6.0.0 中被弃用，此后已被移除。

Intl.v8BreakIterator 是一个非标准扩展，已被移除。参见 Intl.Segmenter。

未处理的 Promise 拒绝已弃用。默认情况下，未处理的 Promise 拒绝会以非零退出码终止 Node.js 进程。要更改 Node.js 处理未处理拒绝的方式，请使用 --unhandled-rejections 命令行选项。

在某些情况下，require('.') 可能解析到包目录外部。此行为已被移除。

Server.connections 属性在 Node.js 0.9.7 中被弃用，此后已被移除。请改用 Server.getConnections() 方法。

Server.listenFD() 方法已弃用并被移除。请改用 Server.listen({fd: <number>})。

os.tmpDir() API 在 Node.js 7.0.0 中被弃用，此后已被移除。请改用 os.tmpdir()。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/tmpDir-to-tmpdir

os.getNetworkInterfaces() 方法已弃用。请改用 os.networkInterfaces() 方法。

REPLServer.prototype.convertToContext() API 已被移除。

类型：运行时

node:sys 模块已弃用。请改用 util 模块。

util.print() 已被移除。请改用 console.log()。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-print-to-console-log

util.puts() 已被移除。请改用 console.log()。

可用的自动迁移工具（来源）：

npx codemod@latest @nodejs/util-print-to-console-log

util.debug() 已被移除。请改用 console.error()。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-print-to-console-log

util.error() 已被移除。请改用 console.error()。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-print-to-console-log

SlowBuffer 类已被移除。请改用 Buffer.allocUnsafeSlow(size)。

自动迁移工具可用（来源）。

npx codemod@latest @nodejs/slow-buffer-to-buffer-alloc-unsafe-slow

类型：运行时

ecdh.setPublicKey() 方法现已弃用，因为其在 API 中的包含并无用处。

类型：运行时

domain 模块已弃用，不应使用。加载该模块会发出运行时弃用警告。

events.listenerCount(emitter, eventName) API 曾被弃用，因为它与 emitter.listenerCount(eventName) 提供了相同的功能。弃用已被撤销，因为此函数已重新用于同时接受 EventTarget 参数。

fs.exists(path, callback) API 已弃用。请改用 fs.stat() 或 fs.access()。

类型：仅文档

fs.lchmod(path, mode, callback) API 已弃用。

类型：仅文档

fs.lchmodSync(path, mode) API 已弃用。

fs.lchown(path, uid, gid, callback) API 曾被弃用。弃用已撤销，因为必要的支持 API 已添加到 libuv 中。

fs.lchownSync(path, uid, gid) API 曾被弃用。弃用已撤销，因为必要的支持 API 已添加到 libuv 中。

类型：仅文档

require.extensions 属性已弃用。

punycode 模块已弃用。请改用用户空间的替代方案。

NODE_REPL_HISTORY_FILE 环境变量已被移除。请改用 NODE_REPL_HISTORY。

tls.CryptoStream 类已被移除。请改用 tls.TLSSocket。

tls.SecurePair 类已弃用。请改用 tls.TLSSocket。

类型：运行时

util.isArray() API 已弃用。请改用 Array.isArray()。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isBoolean() API 已被移除。请改用 typeof arg === 'boolean'。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isBuffer() API 已被移除。请改用 Buffer.isBuffer()。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isDate() API 已被移除。请改用 arg instanceof Date。

如需更强大的方法，请考虑使用： Date.prototype.toString.call(arg) === '[object Date]' && !isNaN(arg)。 这也可用于 try/catch 块中，以处理无效的日期对象。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isError() API 已被移除。请改用 Error.isError(arg)。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isFunction() API 已被移除。请改用 typeof arg === 'function'。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isNull() API 已被移除。请改用 arg === null。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isNullOrUndefined() API 已被移除。请改用 arg === null || arg === undefined。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isNumber() API 已被移除。请改用 typeof arg === 'number'。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isObject() API 已被移除。请改用 arg && typeof arg === 'object'。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isPrimitive() API 已被移除。请改用 Object(arg) !== arg。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isRegExp() API 已被移除。请改用 arg instanceof RegExp。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isString() API 已被移除。请改用 typeof arg === 'string'。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isSymbol() API 已被移除。请改用 typeof arg === 'symbol'。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.isUndefined() API 已被移除。请改用 arg === undefined。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-is

util.log() API 已被移除，因为它是一个意外暴露给用户空间的未维护遗留 API。相反，请根据您的具体需求考虑以下替代方案：

• 第三方日志库

• 使用 console.log(new Date().toLocaleString(), message)

通过采用这些替代方案之一，您可以逐步远离 util.log()，并选择符合您应用程序特定要求和复杂性的日志策略。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-log-to-console-log

类型：运行时

util._extend() API 已弃用，因为它是一个意外暴露给用户空间的未维护遗留 API。 请改用 target = Object.assign(target, source)。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/util-extend-to-object-assign

fs.SyncWriteStream 类从未打算成为公开可访问的 API，已被移除。没有可用的替代 API。请使用用户空间中的替代方案。

--debug 激活了遗留的 V8 调试器接口，该接口自 V8 5.8 起已被移除。它已被 Inspector 取代，后者通过 --inspect 激活。

node:http 模块的 ServerResponse.prototype.writeHeader() API 已弃用。请改用 ServerResponse.prototype.writeHead()。

ServerResponse.prototype.writeHeader() 方法从未被记录为官方支持的 API。

tls.createSecurePair() API 在 Node.js 0.11.3 的文档中被弃用。用户应改用 tls.Socket。

提供了自动迁移工具（源代码）：

npx codemod @nodejs/tls-create-secure-pair-to-tls-socket

node:repl 模块的 REPL_MODE_MAGIC 常量（用于 replMode 选项）已被移除。自 Node.js 6.0.0 导入 V8 5.0 以来，其行为在功能上与 REPL_MODE_SLOPPY 相同。请改用 REPL_MODE_SLOPPY。

NODE_REPL_MODE 环境变量用于设置交互式 node 会话的底层 replMode。其值 magic 也被移除。请改用 sloppy。

node:http 模块的 OutgoingMessage.prototype._headers 和 OutgoingMessage.prototype._headerNames 属性已弃用。使用公共方法之一（例如 OutgoingMessage.prototype.getHeader()、OutgoingMessage.prototype.getHeaders()、OutgoingMessage.prototype.getHeaderNames()、OutgoingMessage.prototype.getRawHeaderNames()、OutgoingMessage.prototype.hasHeader()、OutgoingMessage.prototype.removeHeader()、OutgoingMessage.prototype.setHeader()）来处理传出的标头。

OutgoingMessage.prototype._headers 和 OutgoingMessage.prototype._headerNames 属性从未被记录为官方支持的属性。

自动迁移工具可用（来源）：

npx codemod@latest @nodejs/http-outgoingmessage-headers

类型：仅文档

node:http 模块的 OutgoingMessage.prototype._renderHeaders() API 已弃用。

OutgoingMessage.prototype._renderHeaders 属性从未被记录为官方支持的 API。

node debug 对应于传统的 CLI 调试器，它已被基于 V8-inspector 的 CLI 调试器取代，后者可通过 node inspect 使用。

DebugContext 已在 V8 中被移除，在 Node.js 10+ 中不可用。

DebugContext 曾是一个实验性 API。

async_hooks.currentId() 已重命名为 async_hooks.executionAsyncId() 以提高清晰度。

此更改是在 async_hooks 作为实验性 API 时进行的。

async_hooks.triggerId() 已重命名为 async_hooks.triggerAsyncId() 以提高清晰度。

此更改是在 async_hooks 作为实验性 API 时进行的。

async_hooks.AsyncResource.triggerId() 已重命名为 async_hooks.AsyncResource.triggerAsyncId() 以提高清晰度。

此更改是在 async_hooks 作为实验性 API 时进行的。

访问 net.Server 实例的几个具有不适当名称的内部、未文档化属性已弃用。

由于原始 API 未文档化且通常对非内部代码无用，因此不提供替代 API。

REPLServer.bufferedCommand 属性已弃用，推荐使用 REPLServer.clearBufferedCommand()。

REPLServer.parseREPLKeyword() 已从用户空间可见性中移除。

tls.parseCertString() 是一个因疏忽而公开的简单解析辅助函数。尽管它原本用于解析证书主题和颁发者字符串，但它从未正确处理包含多个值的相对专有名称。

本文档的早期版本曾建议使用 querystring.parse() 作为 tls.parseCertString() 的替代方案。然而，querystring.parse() 同样无法正确处理所有证书主题，因此不应使用。

Module._debug() 已被移除。

Module._debug() 函数从未被文档化为官方支持的 API。

REPLServer.turnOffEditorMode() 不再对用户空间可见。

在对象上使用名为 inspect 的属性来为 util.inspect() 指定自定义检查函数已弃用。请改用 util.inspect.custom。为了与 6.4.0 版本之前的 Node.js 保持向后兼容，两者都可以指定。

类型：仅文档

内部 path._makeLong() 并非旨在供公开使用。然而， 用户空间模块发现它很有用。内部 API 已弃用， 并替换为相同的公共 path.toNamespacedPath() 方法。

fs.truncate() fs.truncateSync() 与文件描述符一起使用已 弃用。请使用 fs.ftruncate() 或 fs.ftruncateSync() 来处理 文件描述符。

自动迁移可用（来源）：

npx codemod@latest @nodejs/fs-truncate-fd-deprecation

REPLServer.prototype.memory() 仅对 REPLServer 本身的内部机制是必要的。不要使用此函数。

tls.createSecureContext() 和 tls.TLSSocket 的 ecdhCurve 选项可以 设置为 false 以仅在服务器上完全禁用 ECDH。此模式已 弃用，以准备迁移到 OpenSSL 1.1.0 并与客户端保持一致，现在不再支持。请改用 ciphers 参数。

自 Node.js 版本 4.4.0 和 5.2.0 以来，几个仅用于 内部使用的模块被错误地通过 require() 暴露给用户代码。这些模块是：

• v8/tools/codemap
• v8/tools/consarray
• v8/tools/csvparser
• v8/tools/logreader
• v8/tools/profile_view
• v8/tools/profile
• v8/tools/SourceMap
• v8/tools/splaytree
• v8/tools/tickprocessor-driver
• v8/tools/tickprocessor
• node-inspect/lib/_inspect（从 7.6.0 开始）
• node-inspect/lib/internal/inspect_client（从 7.6.0 开始）
• node-inspect/lib/internal/inspect_repl（从 7.6.0 开始）

v8/* 模块没有任何导出，如果不按特定顺序导入，实际上会抛出错误。因此，通过 require() 导入它们几乎没有合法的用例。

另一方面，node-inspect 可以通过包管理器在本地安装，因为它以相同的名称发布在 npm 注册表上。如果这样做，则无需修改源代码。

AsyncHooks 敏感 API 从未被文档化，并且存在各种小问题。 请改用 AsyncResource API。参见 https://github.com/nodejs/node/issues/15572。

runInAsyncIdScope 不发出 'before' 或 'after' 事件，因此可能导致 很多问题。参见 https://github.com/nodejs/node/issues/14328。

不建议直接导入 assert，因为其公开的函数使用 宽松相等性检查。弃用已被撤销，因为使用 node:assert 模块并不受劝阻，且该弃用引起了开发者的困惑。

Node.js 曾支持在调用 decipher.setAuthTag() 时使用 OpenSSL 接受的所有 GCM 身份验证标签长度。从 Node.js v11.0.0 开始，仅允许使用长度为 128、120、112、104、96、64 和 32 位的身份验证标签。根据 NIST SP 800-38D，其他长度的身份验证标签均无效。

crypto.DEFAULT_ENCODING 属性仅为了与 0.9.3 版本之前的 Node.js 发布版本兼容而存在，现已移除。

将属性分配给顶层 this 作为 module.exports 的替代方案已弃用。开发者应改用 exports 或 module.exports。

类型：运行时

crypto.fips 属性已弃用。请改用 crypto.setFips() 和 crypto.getFips()。

自动迁移可用（来源）。

npx codemod@latest @nodejs/crypto-fips-to-getFips

使用多个参数调用 assert.fail() 已弃用。请仅使用 一个参数调用 assert.fail()，或使用不同的 node:assert 模块 方法。

timers.enroll() 已被移除。请改用公开文档化的 setTimeout() 或 setInterval()。

自动迁移工具现已可用（来源）。

npx codemod @nodejs/timers-deprecations

timers.unenroll() 已被移除。请改用公开文档化的 clearTimeout() 或 clearInterval()。

现已提供自动迁移工具（来源）。

npx codemod @nodejs/timers-deprecations

异步资源和 MakeCallback 上的 domain 属性已被移除。 domain 模块现在使用 AsyncLocalStorage 进行上下文传播， 而不是 async_hooks。访问 AsyncResource 上的 domain 属性将抛出 错误。请改用 AsyncLocalStorage 进行上下文传播。

AsyncHooks 提供的嵌入 API 暴露了 .emitBefore() 和 .emitAfter() 方法，这些方法非常容易被错误使用，从而导致 不可恢复的错误。

请改用 asyncResource.runInAsyncScope() API，它提供了更安全、 更方便的替代方案。参见 https://github.com/nodejs/node/pull/18513。

类型：编译时

某些版本的 node::MakeCallback API（可供原生插件使用）已 弃用。请使用接受 async_context 参数的 API 版本。

process.assert() 已弃用。请改用 assert 模块。

这从未是一个有文档记录的功能。

可使用自动迁移（来源）。

npx codemod@latest @nodejs/process-assert-to-node-assert

--with-lttng 编译时选项已被移除。

使用 noAssert 参数不再有任何作用。无论 noAssert 的值如何，所有输入都会 被验证。跳过验证可能导致难以发现的错误和崩溃。

通常应避免使用 process.binding()。特别是类型检查 方法可以通过使用 util.types 来替换。

此弃用已被 process.binding() API 的弃用所取代 (DEP0111)。

当将非字符串属性分配给 process.env 时，分配的值会 隐式转换为字符串。如果分配的值不是字符串、布尔值或数字，则此行为已弃用。将来，此类分配可能会 导致抛出错误。请在将其分配给 process.env 之前将属性转换为字符串。

decipher.finaltol() 从未被文档化，它是 decipher.final() 的别名。此 API 已被移除，建议使用 decipher.final() 代替。

crypto.createCipher() 和 crypto.createDecipher() 已被移除， 因为它们使用弱密钥派生函数（无盐的 MD5）和静态 初始化向量。 建议使用 crypto.pbkdf2() 或 crypto.scrypt() 与随机盐派生密钥，并使用 crypto.createCipheriv() 和 crypto.createDecipheriv() 分别获取 Cipheriv 和 Decipheriv 对象。

提供了自动迁移工具（源代码）：

npx codemod @nodejs/crypto-createcipheriv-migration

这是一个未文档化的辅助函数，不适用于 Node.js 核心之外的使用，并且随着 NPN（下一代协议协商）支持的移除而过时。

zlib.bytesWritten 的已弃用别名。选择这个原始名称是因为 将其值解释为引擎读取的字节数也有意义，但与 Node.js 中 在这些名称下暴露值的其他流不一致。

自动迁移可用（来源）。

npx codemod@latest @nodejs/zlib-bytesread-to-byteswritten

一些以前支持（但严格无效）的 URL 被 http.request()、http.get()、https.request()、 https.get() 和 tls.checkServerIdentity() API 接受，因为这些 URL 被传统的 url.parse() API 接受。提到的 API 现在使用 WHATWG URL 解析器，该解析器需要严格有效的 URL。传递无效 URL 已 弃用，支持将在未来移除。

produceCachedData 选项已弃用。请改用 script.createCachedData()。

process.binding() 仅供 Node.js 内部代码使用。

虽然 process.binding() 通常尚未达到生命周期结束状态，但在启用 权限模型 时不可用。

node:dgram 模块以前包含几个从未旨在 在 Node.js 核心之外访问的 API：Socket.prototype._handle、 Socket.prototype._receiving、Socket.prototype._bindState、 Socket.prototype._queue、Socket.prototype._reuseAddr、 Socket.prototype._healthCheck()、Socket.prototype._stopReceiving() 和 dgram._createSocketHandle()。这些已被移除。

Cipher.setAuthTag() 和 Decipher.getAuthTag() 不再可用。它们 从未被文档化，并且在调用时会抛出错误。

crypto._toBuf() 函数并非设计用于 Node.js 核心之外的模块，已被移除。

在最近版本的 Node.js 中，crypto.randomBytes() 和 crypto.pseudoRandomBytes() 之间没有区别。后者已 弃用，连同未文档化的别名 crypto.prng() 和 crypto.rng() 一起，推荐使用 crypto.randomBytes()，并可能在未来的版本中移除。

[传统 URL API][] 已弃用。这包括 url.format()、 url.parse()、url.resolve() 和 [传统 urlObject][]。请改用 WHATWG URL API。

自动迁移可用（来源）。

npx codemod@latest @nodejs/node-url-to-whatwg-url

早期版本的 Node.js 通过 Cipher、Decipher、DiffieHellman、 DiffieHellmanGroup、ECDH、Hash、Hmac、Sign 和 Verify 类的 _handle 属性暴露了内部原生对象的句柄。 _handle 属性已被移除，因为不当使用原生 对象可能导致应用程序崩溃。

早期版本的 Node.js 支持使用假值主机名（如 dns.lookup(false)）调用 dns.lookup()，这是出于向后兼容性考虑。此支持已被移除。

process.binding('uv').errname() 已弃用。请改用 util.getSystemErrorName()。

Windows 性能计数器支持已从 Node.js 中移除。 未文档化的 COUNTER_NET_SERVER_CONNECTION()、 COUNTER_NET_SERVER_CONNECTION_CLOSE()、COUNTER_HTTP_SERVER_REQUEST()、 COUNTER_HTTP_SERVER_RESPONSE()、COUNTER_HTTP_CLIENT_REQUEST() 和 COUNTER_HTTP_CLIENT_RESPONSE() 函数已弃用。

未文档化的 net._setSimultaneousAccepts() 函数最初 旨在用于在 Windows 上使用 node:child_process 和 node:cluster 模块时进行调试和性能调优。该函数通常 无用，正在被移除。参见此处的讨论： https://github.com/nodejs/node/issues/18391

请改用 Server.prototype.setSecureContext()。

RFC 6066 不允许将 TLS ServerName 设置为 IP 地址。

此属性是对实例本身的引用。

node:_stream_wrap 模块已弃用。

以前未文档化的 timers.active() 已被移除。 请改用公开文档化的 timeout.refresh()。 如果需要重新引用超时，timeout.ref() 可以自 Node.js 10 以来使用，且无性能影响。

自动迁移工具现已可用（源代码）。

npx codemod @nodejs/timers-deprecations

以前未文档化且“私有”的 timers._unrefActive() 已被移除。 请改用公开文档化的 timeout.refresh()。 如果需要取消引用超时，timeout.unref() 可以自 Node.js 10 以来使用，且无性能影响。

自动迁移工具可用（源代码）。

npx codemod @nodejs/timers-deprecations

类型：运行时

具有无效 main 入口（例如 ./does-not-exist.js）且 在顶层目录中也有 index.js 文件的模块将解析 index.js 文件。这已弃用，并将在未来的 Node.js 版本中抛出错误。

spawn() 和类似函数返回的子进程对象的 _channel 属性不适合公开使用。请改用 ChildProcess.channel。

请改用 module.createRequire()。

自动迁移可用（来源）：

npx codemod@latest @nodejs/create-require-from-path

传统 HTTP 解析器在 12.0.0 版本之前的 Node.js 版本中默认使用， 已弃用并在 v13.0.0 中移除。在 v13.0.0 之前， 可以使用 --http-parser=legacy 命令行标志恢复使用传统解析器。

传递回调给 worker.terminate() 已弃用。请改用返回的 Promise，或监听 worker 的 'exit' 事件。

类型：仅文档

首选 response.socket 而不是 response.connection， 首选 request.socket 而不是 request.connection。

process._tickCallback 属性从未被文档化为 官方支持的 API。

WriteStream.open() 和 ReadStream.open() 是未文档化的内部 API，在用户空间中使用没有意义。文件流应始终通过其相应的工厂方法 fs.createWriteStream() 和 fs.createReadStream() 打开，或在选项中传递文件描述符。

类型：仅文档

response.finished 指示是否已调用 response.end(), 而不是是否已发出 'finish' 且底层数据 已刷新。

请相应地改用 response.writableFinished 或 response.writableEnded 以避免歧义。

为了保持现有行为，response.finished 应替换为 response.writableEnded。

允许 fs.FileHandle 对象在垃圾回收时关闭曾经是 允许的，但现在会抛出错误。

请确保所有 fs.FileHandle 对象在不再需要时使用 FileHandle.prototype.close() 显式关闭：

const fsPromises = require('node:fs').promises;
async function openAndClose() {
  let filehandle;
  try {
    filehandle = await fsPromises.open('thefile.txt', 'r');
  } finally {
    if (filehandle !== undefined)
      await filehandle.close();
  }
}

类型：仅文档

process.mainModule 是仅限 CommonJS 的功能，而 process 全局 对象会与非 CommonJS 环境共享。它在 ECMAScript 模块中的使用不受支持。

它已弃用，推荐使用 require.main，因为它用于相同的 目的，且仅在 CommonJS 环境中可用。

可使用自动迁移（来源）：

npx codemod@latest @nodejs/process-main-module

类型：仅文档

调用无参数的 process.umask() 会导致进程范围的 umask 被 写入两次。这在线程之间引入了竞态条件，并且是一个 潜在的安全漏洞。没有安全、跨平台的替代 API。

类型：仅文档

请改用 request.destroy() 而不是 request.abort()。

node:repl 模块导出了输入和输出流两次。请改用 .input 而不是 .inputStream，改用 .output 而不是 .outputStream。

node:repl 模块导出了一个包含内置模块数组的 _builtinLibs 属性。它目前不完整，最好依赖 require('node:module').builtinModules。

自动迁移可用（来源）：

npx codemod@latest @nodejs/repl-builtin-modules

Transform._transformState 将在未来版本中移除，届时由于实现的简化，它将不再需要。

CommonJS 模块可以使用 module.parent 访问第一个 require 它的模块。此功能已弃用，因为它在存在 ECMAScript 模块的情况下不能一致地工作，并且因为它给出了 CommonJS 模块图的不准确表示。

一些模块使用它来检查它们是否是当前进程的入口点。 相反，建议比较 require.main 和 module：

if (require.main === module) {
  // 仅当当前文件是入口点时才会运行的代码部分。
}

当查找 require 当前模块的 CommonJS 模块时， 可以使用 require.cache 和 module.children：

const moduleParents = Object.values(require.cache)
  .filter((m) => m.children.includes(module));

类型：仅文档

socket.bufferSize 只是 writable.writableLength 的别名。

类型：仅文档

crypto.Certificate() 构造函数 已弃用。请改用 crypto.Certificate() 的静态方法。

fs.rmdir、fs.rmdirSync 和 fs.promises.rmdir 方法曾经 支持 recursive 选项。该选项已被移除。

请改用 fs.rm(path, { recursive: true, force: true })、 fs.rmSync(path, { recursive: true, force: true }) 或 fs.promises.rm(path, { recursive: true, force: true })。

自动迁移可用（来源）：

npx codemod@latest @nodejs/rmdir

不再支持在 子路径导出 或 子路径导入 字段中使用尾部 "/" 来定义子路径文件夹映射。 请改用 子路径模式。

首选 message.socket 而不是 message.connection。

process.config 属性提供对 Node.js 编译时设置的访问。 然而，该属性是可变的，因此易受篡改。更改值的能力 将在未来的 Node.js 版本中移除。

以前，index.js 和扩展名搜索查找会应用于 import 'pkg' 主入口点解析，即使在解析 ES 模块时也是如此。

通过此弃用，所有 ES 模块主入口点解析都需要 一个带有确切文件扩展名的显式 "exports" 或 "main" 入口。

'gc'、'http2' 和 'http' PerformanceEntry 对象类型曾经拥有 额外属性，用于提供更多信息。 这些属性现在可在 PerformanceEntry 对象的标准 detail 属性中使用。已弃用的访问器已被 移除。

在 dns.lookup() 和 dnsPromises.lookup() 中对 family 选项使用非空值非整数值，对 hints 选项使用非空值非数字值，对 all 选项使用非空值非布尔值，或对 verbatim 选项使用非空值非布尔值，将抛出 ERR_INVALID_ARG_TYPE 错误。

请使用 'hashAlgorithm' 而不是 'hash'，使用 'mgf1HashAlgorithm' 而不是 'mgf1Hash'。

自动迁移可用（来源）。

npx codemod@latest @nodejs/crypto-rsa-pss-update

类型：运行时

对于包 "exports" 和 "imports" 模式解析，以 "/" 结尾的标识符（如 import 'pkg/x/'）的重映射已弃用。

类型：仅文档

请改用 Stream API，因为 http.ClientRequest、 http.ServerResponse 和 http.IncomingMessage 都是基于流的。 检查 stream.destroyed 而不是 .aborted 属性，并监听 'close' 而不是 'abort'、'aborted' 事件。

.aborted 属性和 'abort' 事件仅对检测 .abort() 调用有用。对于提前关闭请求，使用 Stream .destroy([error])，然后检查 .destroyed 属性和 'close' 事件 应具有相同的效果。接收端还应检查 http.IncomingMessage 上的 readable.readableEnded 值，以获取它是 被中止还是优雅销毁。

Node.js 流的一个未文档化功能是在 实现方法中支持 thenables。这现已弃用，请改用回调，并避免 在流实现方法中使用异步函数。

此功能导致用户遇到意外问题，即用户使用回调风格实现函数，但使用了例如异步方法，这将导致错误，因为混合 Promise 和回调语义是无效的。

const w = new Writable({
  async final(callback) {
    await someOp();
    callback();
  },
});

类型：仅文档

此方法已被弃用，因为它与 Uint8Array.prototype.slice() 不兼容，而后者是 Buffer 的超类。

请改用 buffer.subarray，它执行相同的操作。

此错误代码已被移除，因为它给用于值类型验证的错误增加了更多的混淆。

提供了自动迁移工具（来源）：

npx codemod @nodejs/err-invalid-callback

此事件已被弃用并移除，因为它不适用于 V8 Promise 组合器，从而降低了其有用性。

类型：仅文档

process._getActiveHandles() 和 process._getActiveRequests() 函数并非旨在供公开使用，并可能在未来的版本中被移除。

请使用 process.getActiveResourcesInfo() 来获取活动资源类型的列表，而不是实际的引用。

在 fs.write()、fs.writeFile()、fs.appendFile()、fs.writeFileSync() 和 fs.appendFileSync() 中作为第二个参数传递的、具有自有 toString 属性的对象的隐式强制转换已被弃用。请将它们转换为原始字符串。

这些方法已被弃用，因为如果用户没有强引用它们，它们的使用可能会使 channel 对象容易被垃圾回收。弃用已被撤销，因为当 channel 有活动订阅者时，channel 对象现在可以抵抗垃圾回收。

除了 undefined、null、整数和整数字符串（例如 '1'）之外的值，作为 process.exit() 中 code 参数的值以及分配给 process.exitCode 的值已被弃用。

--trace-atomics-wait 标志已被移除，因为它使用了 V8 钩子 SetAtomicsWaitCallback，该钩子将在未来的 V8 版本中被移除。

类型：运行时

包导入和导出目标映射到包含双斜杠（"/" 或 "\\"）的路径已被弃用，并将在未来的版本中因解析验证错误而失败。此弃用同样适用于以斜杠开头或结尾的模式匹配。

类型：仅文档

众所周知的 MODP 组 modp1、modp2 和 modp5 已被弃用，因为它们无法抵御实际攻击。详见 RFC 8247 第 2.4 节。

这些组可能会在未来的 Node.js 版本中被移除。依赖这些组的应用程序应评估使用更强的 MODP 组。

类型：运行时

Node-API 回调中未捕获异常的隐式抑制现已弃用。

设置标志 --force-node-api-uncaught-exceptions-policy 以强制 Node.js 在 Node-API 回调中未处理异常时发出 'uncaughtException' 事件。

url.parse() 行为未标准化且容易出错，具有安全隐患。请改用 WHATWG URL API。不会为 url.parse() 漏洞发布 CVE。

调用 url.format(urlString) 或 url.resolve() 会在内部调用 url.parse()，因此也受此弃用的约束。

url.parse() 过去接受端口不是数字的 URL。此行为可能导致主机名欺骗和意外输入。这些 URL 将抛出错误（WHATWG URL API 也会这样做）。

类型：仅文档

在未来的 Node.js 版本中，message.headers、message.headersDistinct、message.trailers 和 message.trailersDistinct 将是只读的。

旧版本的 Node.js 会在函数绑定到 AsyncResource 时添加 asyncResource。现在不再这样做。

assert.CallTracker API 已被移除。

类型：运行时

对返回 Promise 的函数调用 util.promisify 将忽略该 Promise 的结果，这可能导致未处理的 Promise 拒绝。

类型：仅文档

util.toUSVString() API 已弃用。请改用 String.prototype.toWellFormed。

直接暴露在 node:fs 上的 F_OK、R_OK、W_OK 和 X_OK 获取器已被移除。请改为从 fs.constants 或 fs.promises.constants 获取它们。

提供自动迁移工具 (源码)：

npx codemod@latest @nodejs/fs-access-mode-constants

util.types.isWebAssemblyCompiledModule API 已被移除。请改用 value instanceof WebAssembly.Module。

dirent.path 属性已被移除，因为其在发布版本之间缺乏一致性。请改用 dirent.parentPath。

提供自动迁移工具 (源码）：

npx codemod@latest @nodejs/dirent-path-to-parent-path

类型：运行时

直接使用 Hash() 或 new Hash() 调用 Hash 类已被弃用，因为它是内部实现，并非设计为供公开使用。请使用 crypto.createHash() 方法来创建 Hash 实例。

类型：运行时

直接使用 Stats() 或 new Stats() 调用 fs.Stats 类已被弃用，因为它是内部实现，不适合公开使用。

类型：运行时

直接使用 Hmac() 或 new Hmac() 调用 Hmac 类已被弃用，因为它是内部实现，并非供公开使用。请使用 crypto.createHmac() 方法来创建 Hmac 实例。

对于 GCM 模式的密码，decipher.setAuthTag() 函数过去接受任何有效长度的认证标签（另见 DEP0090）。此例外已被移除，以便更好地符合 NIST SP 800-38D 的建议，打算使用短于默认认证标签长度（即短于 AES-GCM 的 16 字节）的认证标签的应用程序必须显式地将 crypto.createDecipheriv() 函数的 authTagLength 选项设置为适当的长度。

类型：运行时

OpenSSL 3 已弃用对自定义引擎的支持，并建议切换到其新的提供者模型。https.request()、tls.createSecureContext() 和 tls.createServer() 的 clientCertEngine 选项；tls.createSecureContext() 的 privateKeyEngine 和 privateKeyIdentifier；以及 crypto.setEngine() 都依赖于 OpenSSL 的此功能。

实例化 node:zlib 模块导出的类时不使用 new 限定符已不再受支持。必须改用 new 限定符。这适用于所有 Zlib 类，例如 Deflate、DeflateRaw、Gunzip、Inflate、InflateRaw、Unzip、BrotliCompress、BrotliDecompress、ZstdCompress 和 ZstdDecompress。

实例化 node:repl 模块导出的类时不使用 new 限定符已被弃用。必须改用 new 限定符。这适用于所有 REPL 类，包括 REPLServer 和 Recoverable。

提供自动迁移工具（源码）：

npx codemod@latest @nodejs/repl-classes-with-new

类型：运行时

传递不支持的参数类型已被弃用，并且在未来的版本中将抛出错误，而不是返回 false。

类型：仅文档

这些属性无条件为 true。基于这些属性的任何检查都是多余的。

类型：仅文档

process.features.tls_alpn、process.features.tls_ocsp 和 process.features.tls_sni 已弃用，因为它们的值保证与 process.features.tls 的值相同。

类型：运行时

当将 args 数组传递给 child_process.execFile 或 child_process.spawn 并带有选项 { shell: true } 或 { shell: '/path/to/shell' } 时，值不会被转义，仅以空格分隔，这可能导致 Shell 注入。

node:repl 模块导出一个 builtinModules 属性，其中包含内置模块数组。该数组不完整，并且与已弃用的 repl._builtinLibs (DEP0142) 相匹配，因此最好依赖 require('node:module').builtinModules。

提供自动迁移工具 (源码)：

npx codemod@latest @nodejs/repl-builtin-modules

node:_tls_common 和 node:_tls_wrap 模块已弃用，因为它们应被视为内部 Node.js 实现而不是公开 API，请改用 node:tls。

node:_stream_duplex、node:_stream_passthrough、node:_stream_readable、node:_stream_transform、node:_stream_wrap 和 node:_stream_writable 模块已弃用，因为它们应被视为 Node.js 的内部实现，而不是公开 API，请改用 node:stream。

对在 RFC 9113 中弃用的优先级信令的支持已被移除。

自动迁移功能可用（源代码）：

npx codemod@latest @nodejs/http2-priority-signaling

类型：运行时

不使用 new 关键字实例化由 node:http 模块导出的类已被弃用。 建议改用 new 关键字。这适用于所有 HTTP 类，例如 OutgoingMessage、IncomingMessage、ServerResponse、ClientRequest、Server 和 Agent。

提供自动迁移工具 (源码)：

npx codemod@latest @nodejs/http-classes-with-new

类型：仅文档

使用 { shell: '' } 调用进程生成函数几乎肯定是有意的，并且可能导致异常行为。

要使 child_process.execFile 或 child_process.spawn 调用默认 shell，请使用 { shell: true }。如果意图是不调用 shell（默认行为），要么省略 shell 选项，要么将其设置为 false 或 nullish 值。

要使 child_process.exec 调用默认 shell，要么省略 shell 选项，要么将其设置为 nullish 值。如果意图是不调用 shell，请改用 child_process.execFile。

util.types.isNativeError API 已弃用。请改用 Error.isError。

提供自动迁移工具 (源码)：

npx codemod@latest @nodejs/types-is-native-error

创建 SHAKE-128 和 SHAKE-256 摘要时，如果没有显式的 options.outputLength，则不再受支持。

类型：仅文档

node:_http_agent、node:_http_client、node:_http_common、node:_http_incoming、node:_http_outgoing 和 node:_http_server 模块已弃用，因为它们应被视为内部 Node.js 实现而不是公开 API，请改用 node:http。

类型：仅文档

允许 fs.Dir 对象在垃圾回收时关闭已被弃用。在未来，这样做可能会导致抛出错误并终止进程。

请确保所有 fs.Dir 对象都使用 Dir.prototype.close() 或 using 关键字显式关闭：

import { opendir } from 'node:fs/promises';

{
  await using dir = await opendir('/async/disposable/directory');
} // 由 dir[Symbol.asyncDispose]() 关闭

{
  using dir = await opendir('/sync/disposable/directory');
} // 由 dir[Symbol.dispose]() 关闭

{
  const dir = await opendir('/unconditionally/iterated/directory');
  for await (const entry of dir) {
    // 处理条目
  } // 由迭代器关闭
}

{
  let dir;
  try {
    dir = await opendir('/legacy/closeable/directory');
  } finally {
    await dir?.close();
  }
}

类型：运行时

传递 type 选项给 Duplex.toWeb() 已被弃用。要指定构造的可读 - 可写对的可读部分的类型，请改用 readableType 选项。

类型：仅文档

http2.createServer() 和 http2.createSecureServer() 的 Http1IncomingMessage 和 Http1ServerResponse 选项已弃用。请改用 http1Options.IncomingMessage 和 http1Options.ServerResponse。

// 已弃用
const server = http2.createSecureServer({
  allowHTTP1: true,
  Http1IncomingMessage: MyIncomingMessage,
  Http1ServerResponse: MyServerResponse,
});

// 请改用此项
const server = http2.createSecureServer({
  allowHTTP1: true,
  http1Options: {
    IncomingMessage: MyIncomingMessage,
    ServerResponse: MyServerResponse,
  },
});

向 node:crypto 函数传递 CryptoKey 已不再受支持。

向 KeyObject.from() 传递不可提取的 CryptoKey 已 不再受支持。

类型：运行时

module.register() 已弃用。请改用 module.registerHooks()。

module.register() API 为自定义 ES 模块提供了线程外异步钩子；module.registerHooks() API 提供了类似的钩子，这些钩子是同步的、在线程内运行的，并且适用于所有类型的模块。 事实证明，支持异步钩子十分复杂，其中涉及工作线程编排，并且存在一些已被证明无法解决的问题。请参阅异步自定义钩子的注意事项。由于 module.register() 将在 Node.js 的未来版本中移除，请尽快迁移到 module.registerHooks()。

类型：运行时

多次调用 hmac.digest() 会返回一个空缓冲区，而不是抛出错误。此行为与 hash.digest() 不一致，并可能导致隐蔽的错误。在已完成最终化的 Hmac 实例上调用 hmac.digest() 将在未来版本中抛出错误。

类型：仅文档

请改用标准流事件和状态检查。读取端中止 （对端在发送 END_STREAM 之前取消）现在会表现为 'error' ，并带有代码 ERR_HTTP2_STREAM_ABORTED（干净的对端重置代码）或 ERR_HTTP2_STREAM_ERROR（非干净代码）。写入端中止（在我们仍有写入 在飞行中时对端取消）可以通过检查 'close' 的 writableFinished 来检测。与 DEP0156 在 http 上的情况类似。

// 已弃用
server.on('stream', (stream) => {
  stream.on('aborted', () => {
    // 写入端仍处于打开状态时，流被关闭。
  });
});

// 改用以下方式
server.on('stream', (stream) => {
  // 读取端中止：对端在发送 END_STREAM 之前取消。
  stream.on('error', (err) => {
    if (err.code === 'ERR_HTTP2_STREAM_ABORTED' ||
        err.code === 'ERR_HTTP2_STREAM_ERROR') {
      // 对端在请求进行期间取消了请求。
    }
  });
  // 写入端中止：响应在关闭前未能完全发送。
  stream.on('close', () => {
    if (!stream.writableFinished) {
      // 写入已中止（对端取消、本地销毁等）。
    }
  });
});

兼容性 API 也适用相同的模式（在 http2.createServer((req, res) => …) 上的 req / res）。在读取端，底层流中的错误会从 req 发出。在写入端，你可以使用 res.on('close', …) 通过检查 res.writableFinished 来获知客户端中止，以确认响应在关闭之前是否已成功写入。

类型：运行时

net.Server.prototype._listen2 是一个未公开的别名，指向用于设置监听句柄的内部函数。保留它仅仅是为了让替换该函数的代码继续被 server.listen() 调用；它将在 Node.js 的未来版本中移除。请使用 server.listen()，不要调用或重写 _listen2。

类型：仅文档

使用 AbortSignal 销毁长生命周期资源已弃用。建议使用 using 清理资源。

AbortSignal 仍适用于取消操作、从外部传播取消信号以及处理超时。

// 已弃用
async function example() {
  const ac = new AbortController();
  const server = http.createServer(handler);
  server.listen({ port: 3000, signal: ac.signal });

  await doWork();
  ac.abort();
}

// 请改用此方式
async function example() {
  await using server = http.createServer(handler);
  server.listen(3000);

  await doWork();
}

// 已弃用
async function example() {
  const ac = new AbortController();
  const stream = addAbortSignal(ac.signal, fs.createReadStream(file));

  await consume(stream);
  ac.abort();
}

// 请改用此方式
async function example() {
  await using stream = fs.createReadStream(file);

  await consume(stream);
}

// 已弃用
async function example() {
  const ac = new AbortController();
  const child = spawn(command, args, { signal: ac.signal });

  await doWork();
  ac.abort();
}