Node.js 兼容性

编写 Worker 时，你可能需要从 npm ↗ 导入包。许多 npm 包依赖 Node.js 运行时 ↗ 的 API，若这些 Node.js API 不可用，它们将无法工作。

Cloudflare Workers 以两种形式提供 Node.js API 的子集：

1. 作为 Workers 运行时提供的内置 API。其中大多数 API 是对应 Node.js API 的完整实现，少数为部分支持。
2. 作为 polyfill 垫片实现，由 Wrangler 添加到你的 Worker 代码中，允许导入模块，但调用 API 方法会抛出错误。

要启用内置 Node.js API 并添加 polyfill，请在你的 Wrangler 配置文件 中添加 nodejs_compat 兼容性标志，并确保 Worker 的兼容性日期为 2024-09-23 或更晚。详细了解 Node.js 兼容性标志和 v2。

{
	"compatibility_flags": ["nodejs_compat"],
	// Set this to today's date
	"compatibility_date": "2026-08-17",
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"

本节中列出的 Node.js 运行时 API，状态为「🟢 已支持」的，目前在 Workers 运行时中原生支持。状态为「🟡 部分支持」的项包含可用的 API，但未实现完整的 Node.js API 表面。

Node.js 中已弃用或实验性的 API ↗，以及不适合无服务器上下文的 API，未包含在本节的支持 API 列表中。其中一些仅用于导入的桩模块在非功能性桩模块中单独列出。

除非另有说明，Workers 中 Node.js API 的原生实现旨在与 Node.js 当前版本 ↗ 的实现保持一致。

如果你希望使用的 API 尚未提供，并建议 Workers 支持它，请在 GitHub 的 Node.js API 讨论分类 ↗ 中发帖或评论。

部分 Node.js 模块以非功能性桩的形式提供。桩可以导入或 require，但不提供底层 Node.js API 的工作实现。这些桩的存在是为了让检查模块是否存在的包能在 Workers 中加载，但不适合在应用代码中直接使用。

以下桩仅在启用 nodejs_compat 兼容性标志且 Worker 兼容性日期为所示日期或更晚时自动启用。若要更早启用，请添加相应的 enable 标志。若要在该日期之后仍保持不可用，请添加相应的 disable 标志。

Workers 运行时中尚未支持的 Node.js API 通过 Wrangler 进行 polyfill，Wrangler 使用 unenv ↗。若启用了 nodejs_compat 兼容性标志，且 Worker 的兼容性日期为 2024-09-23 或更晚，Wrangler 会自动将 polyfill 注入到你的 Worker 代码中。

添加 polyfill 可最大化与现有 npm 包的兼容性，提供带有模拟方法的模块。调用这些模拟方法要么无操作，要么抛出类似以下消息的错误：

[unenv] <method name> is not implemented yet!

这允许你导入使用这些 Node.js 模块的包，即使某些方法尚未支持。

若只需启用 Node.js AsyncLocalStorage API，可启用 nodejs_als 兼容性标志：

{
	"compatibility_flags": ["nodejs_als"],
}

compatibility_flags = [ "nodejs_als" ]