Cloudflare Workersenable_nodejs_vm_module兼容性标志详解node:vm模块 Stub 的启用时机与配置方法【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本文以 Cloudflare 官方文档仓库 cloudflare-docs 中的 enable-nodejs-vm-module.md 为核心系统讲解 Workers 运行时中enable_nodejs_vm_module兼容性标志Compatibility Flag的作用、默认启用日期以及如何通过 Wrangler 配置、Cloudflare Dashboard 或 API 对该标志进行精确控制。读完本文你将理解node:vm在 Workers 中的非功能 Stub定位掌握启用/禁用该模块的标准操作并能在遇到 npm 包因缺少node:vm而报错时快速定位与修复。一、node:vm模块与 Workers 中的 Stub 定位1.1 Node.js 中的node:vm是什么在 Node.js 生态中node:vmVMVirtual Machine模块提供了一组用于在 V8 虚拟机上下文中编译并运行 JavaScript 代码的 API。典型能力包括在独立的 V8 上下文vm.createContext中执行脚本与宿主上下文隔离通过vm.runInContext、vm.runInNewContext、vm.runInThisContext等接口控制脚本执行环境通过vm.Script预编译代码实现一次编译、多次执行。这些 API 被许多 npm 包用作沙箱执行、模板引擎或代码热加载的底层设施。1.2 Workers 提供的是非功能 Stub而非完整实现Cloudflare Workers 运行时的 Node.js 兼容层并没有把node:vm的全部 API 原样搬进无服务器环境。根据 nodejs-compat.mdx 与 Node.js 运行时 API 文档 的说明node:vm属于非功能 Stub 模块Non-functional stub modules这些模块可以被import或require但不提供对应 Node.js API 的可工作实现。Stub 存在的意义是让那些会探测模块是否存在的 npm 包能够在 Workers 中正常加载不应在业务代码中直接使用。也就是说node:vm的 Stub 承担的是占位符角色当某个第三方包为了判断运行环境而执行require(node:vm)或import node:vm时导入不会抛错包得以继续加载但如果你真的调用new vm.Script(...)之类的方法不会得到真实的 VM 执行能力。二、enable_nodejs_vm_module标志的完整语义enable_nodejs_vm_module标志本身由本仓库的兼容性标志文档直接定义原始声明位于 enable-nodejs-vm-module.md 的 Frontmatter 中元数据字段值标志名称nameEnablenode:vmmodule默认启用日期enable_date2025-10-01排序日期sort_date2025-10-01启用标志enable_flagenable_nodejs_vm_module禁用标志disable_flagdisable_nodejs_vm_module2.1 自动启用规则该标志的启用规则可以概括为一句话当 Worker 的compatibility_date为2025-10-01或之后且已启用nodejs_compat兼容性标志时node:vmStub 会自动启用。其依赖链条为nodejs_compat 标志启用 compatibility_date 2025-10-01 node:vm Stub 自动可用之所以以nodejs_compat为前提是因为node:vm属于 Node.js 兼容体系的一部分。nodejs_compat标志负责在 Workers Runtime 中开启整套 Node.js API而enable_nodejs_vm_module这类子标志则进一步控制其中某一具体模块的生效时机。2.2 标志的三态行为结合 nodejs-compat.mdx 与 compatibility-flags.mdx 中的机制描述该标志的实际行为可用下表概括场景node:vmStub 是否可用未启用nodejs_compat否整个 Node.js 兼容层未开启启用nodejs_compatcompatibility_date2025-10-01否除非手动加enable_nodejs_vm_module启用nodejs_compatcompatibility_date2025-10-01是自动启用已自动启用但显式添加disable_nodejs_vm_module否手动降级保持旧行为这里体现了 Cloudflare 兼容性标志体系的通用设计标志通常有一个按日期默认开启的节点开发者既可以用compatibility_date整体前移来批量采纳新行为也可以单独用 enable/disable 标志在该日期之前提前启用、或在该日期之后回退禁用。三、实际配置操作指南3.1 通过 Wrangler 配置文件wrangler.jsonc / wrangler.toml兼容性标志在 Worker 的 Wrangler 配置文件中通过compatibility_flags数组声明。以下示例先设定一个早于2025-10-01的compatibility_date再显式加入enable_nodejs_vm_module从而提前启用node:vmStub{ // 兼容日期设为 2025-09-01此时 node:vm 尚未默认启用 compatibility_date: 2025-09-01, // 开启 Node.js 兼容层 compatibility_flags: [ nodejs_compat, // 提前启用 node:vm 模块 Stub enable_nodejs_vm_module ] }反过来如果希望回退默认行为例如某个依赖包在探测到node:vm后走了错误的分支逻辑则保留默认日期但追加禁用标志{ // 兼容日期为 2025-10-01 或之后node:vm 默认启用 compatibility_date: 2025-10-01, compatibility_flags: [ nodejs_compat, // 显式禁用让 node:vm 保持不可导入 disable_nodejs_vm_module ] }值得对照的是本仓库自身的 wrangler.jsonc 就是一个真实示例其compatibility_date为2025-06-02compatibility_flags中只声明了nodejs_compat。由于2025-06-02早于2025-10-01在当前配置下node:vmStub不会被自动启用——这正是日期未到则需手动开启的直观印证。3.2 通过 Cloudflare Dashboard在 Cloudflare Dashboard 中进入对应 Worker 的Settings → General → Compatibility flags兼容性标志区域即可在已有的nodejs_compat基础上追加或移除enable_nodejs_vm_module/disable_nodejs_vm_module。Dashboard 中修改的标志会写入 Worker 配置效果与 Wrangler 一致。3.3 通过 Cloudflare API使用 Workers Script API 或 Workers Versions API 上传 Worker 时兼容性标志需要放在请求体metadata字段的compatibility_flags数组中例如{ metadata: { compatibility_date: 2025-09-01, compatibility_flags: [nodejs_compat, enable_nodejs_vm_module] } }关于三种配置入口Wrangler / Dashboard / API的完整说明可参考 compatibility-flags.mdx。四、仓库源码层的实现佐证4.1 标志数据的 Schema 定义本仓库为所有兼容性标志定义了统一的数据结构校验见 src/schemas/compatibility-flags.ts。enable_nodejs_vm_module文档 Frontmatter 中的字段与该 Schema 一一对应export const compatibilityFlagsSchema z.object({ name: z.string(), enable_date: z.string().optional().nullable(), enable_flag: z.string().nullable(), disable_flag: z.string().optional().nullable(), sort_date: z.string(), experimental: z.boolean().optional(), });可以看出每个标志的核心元数据就是启用标志名 禁用标志名 默认启用日期三要素enable_nodejs_vm_module正是这套机制下的标准产物。4.2 机器可读的 JSON 输出仓库通过 compatibility-flags.json.ts 将src/content/compatibility-flags目录下所有标志文档聚合成一个按sort_date排序的 JSON 列表供前端渲染与自动化工具消费。该端点会读取每个文档的 Frontmatter 与正文描述输出包含enable_flag、disable_flag、enable_date等字段的结构化数据——这意味着node:vm模块标志的状态信息可以通过该接口程序化获取。4.3 Stub 模块总表仓库将各类 Node.js Stub 模块的启用日期与标志集中维护在 nodejs-compat-stub-modules.mdx 中node:vm位于该表第二行Stub 模块随nodejs_compat自动启用的日期启用标志禁用标志node:http22025-09-01enable_nodejs_http2_moduledisable_nodejs_http2_modulenode:vm2025-10-01enable_nodejs_vm_moduledisable_nodejs_vm_modulenode:cluster2025-12-04enable_nodejs_cluster_moduledisable_nodejs_cluster_modulenode:domain2025-12-04enable_nodejs_domain_moduledisable_nodejs_domain_modulenode:trace_events2025-12-04enable_nodejs_trace_events_moduledisable_nodejs_trace_events_modulenode:wasi2025-12-04enable_nodejs_wasi_moduledisable_nodejs_wasi_modulenode:_stream_wrap2026-01-29enable_nodejs_stream_wrap_moduledisable_nodejs_stream_wrap_modulenode:dgram2026-01-29enable_nodejs_dgram_moduledisable_nodejs_dgram_modulenode:inspector2026-01-29enable_nodejs_inspector_moduledisable_nodejs_inspector_modulenode:sqlite2026-01-29enable_nodejs_sqlite_moduledisable_nodejs_sqlite_modulenode:child_process2026-03-17enable_nodejs_child_process_moduledisable_nodejs_child_process_modulenode:readline2026-03-17enable_nodejs_readline_moduledisable_nodejs_readline_modulenode:repl2026-03-17enable_nodejs_repl_moduledisable_nodejs_repl_modulenode:tty2026-03-17enable_nodejs_tty_moduledisable_nodejs_tty_modulenode:v82026-03-17enable_nodejs_v8_moduledisable_nodejs_v8_modulenode:worker_threads2026-03-17enable_nodejs_worker_threads_moduledisable_nodejs_worker_threads_module这张表清楚地展示了同类模块的启用节奏node:vm在2025-10-01加入属于较早一批 Stub 化模块之一。五、Node.js 兼容体系的宏观背景为了正确使用该标志还需要理解它所在的nodejs_compat体系开启入口nodejs_compat标志负责在 Workers Runtime 中启用 Node.js API具体支持范围见 Node.js 运行时 API 文档。本仓库自身的 wrangler.jsonc 即声明了compatibility_flags: [nodejs_compat]。未来默认开启根据 nodejs-compat.mdx对2026-08-04及之后的兼容日期Workers 会默认同时启用nodejs_compat与nodejs_compat_v2无需再显式声明这两个标志届时node:vm等 Stub 模块仍遵循各自的按日期启用规则。日期是开关总闸正如 compatibility-dates.mdx 所解释的指定compatibility_date可以一次性采纳该日期之前的所有兼容性变更。将日期前移到2025-10-01之后node:vmStub 就会随nodejs_compat自动就位。六、最佳实践与注意事项不要把 Stub 当真实 API 使用。node:vmStub 仅为模块存在性探测提供占位不提供可工作的 VM 执行能力。如果业务确实需要代码沙箱执行应寻找 Workers 原生的替代方案而不是依赖node:vm。优先升级兼容日期而非手写标志。Cloudflare 官方建议使用最新版 Wrangler CLI 与最新兼容日期以最大化 Node.js 兼容性较新日期下运行时已内置所需 polyfill无需旧版 Wrangler 额外注入。npm 包加载报错时先检查日期。当某个包因缺少node:vm而报Module not found或Cannot find module node:vm时先确认两件事是否已启用nodejs_compat以及compatibility_date是否达到2025-10-01。未达则通过enable_nodejs_vm_module提前开启或直接前移兼容日期。回退需显式禁用。如果升级日期后某个包反而因检测到node:vm走了错误分支可添加disable_nodejs_vm_module单独回退该模块而不影响其余 Node.js API。善用机器可读清单。可通过 compatibility-flags.json.ts 生成的 JSON 接口程序化比对各标志的启用日期与启停标志辅助自动化排查。七、小结enable_nodejs_vm_module是 Cloudflare Workers Node.js 兼容层中一个典型的按日期默认启用、可单独启停的细粒度标志。它确保node:vm模块以非功能 Stub 的形式在 Workers 中可导入从而保证依赖该模块存在性的 npm 包能够正常工作同时把真实的 VM API 排除在无服务器运行时之外。理解它的启用日期2025-10-01、前置条件nodejs_compat与三种配置入口Wrangler / Dashboard / API是排查相关模块加载问题、安全演进兼容日期的基础能力。相关权威细节均可回溯到本仓库的 enable-nodejs-vm-module.md、nodejs-compat.mdx 与 nodejs-compat-stub-modules.mdx。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare Workers `enable_nodejs_vm_module` 兼容性标志详解：`node:vm` 模块 Stub 的启用时机与配置方法
Cloudflare Workersenable_nodejs_vm_module兼容性标志详解node:vm模块 Stub 的启用时机与配置方法【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本文以 Cloudflare 官方文档仓库 cloudflare-docs 中的 enable-nodejs-vm-module.md 为核心系统讲解 Workers 运行时中enable_nodejs_vm_module兼容性标志Compatibility Flag的作用、默认启用日期以及如何通过 Wrangler 配置、Cloudflare Dashboard 或 API 对该标志进行精确控制。读完本文你将理解node:vm在 Workers 中的非功能 Stub定位掌握启用/禁用该模块的标准操作并能在遇到 npm 包因缺少node:vm而报错时快速定位与修复。一、node:vm模块与 Workers 中的 Stub 定位1.1 Node.js 中的node:vm是什么在 Node.js 生态中node:vmVMVirtual Machine模块提供了一组用于在 V8 虚拟机上下文中编译并运行 JavaScript 代码的 API。典型能力包括在独立的 V8 上下文vm.createContext中执行脚本与宿主上下文隔离通过vm.runInContext、vm.runInNewContext、vm.runInThisContext等接口控制脚本执行环境通过vm.Script预编译代码实现一次编译、多次执行。这些 API 被许多 npm 包用作沙箱执行、模板引擎或代码热加载的底层设施。1.2 Workers 提供的是非功能 Stub而非完整实现Cloudflare Workers 运行时的 Node.js 兼容层并没有把node:vm的全部 API 原样搬进无服务器环境。根据 nodejs-compat.mdx 与 Node.js 运行时 API 文档 的说明node:vm属于非功能 Stub 模块Non-functional stub modules这些模块可以被import或require但不提供对应 Node.js API 的可工作实现。Stub 存在的意义是让那些会探测模块是否存在的 npm 包能够在 Workers 中正常加载不应在业务代码中直接使用。也就是说node:vm的 Stub 承担的是占位符角色当某个第三方包为了判断运行环境而执行require(node:vm)或import node:vm时导入不会抛错包得以继续加载但如果你真的调用new vm.Script(...)之类的方法不会得到真实的 VM 执行能力。二、enable_nodejs_vm_module标志的完整语义enable_nodejs_vm_module标志本身由本仓库的兼容性标志文档直接定义原始声明位于 enable-nodejs-vm-module.md 的 Frontmatter 中元数据字段值标志名称nameEnablenode:vmmodule默认启用日期enable_date2025-10-01排序日期sort_date2025-10-01启用标志enable_flagenable_nodejs_vm_module禁用标志disable_flagdisable_nodejs_vm_module2.1 自动启用规则该标志的启用规则可以概括为一句话当 Worker 的compatibility_date为2025-10-01或之后且已启用nodejs_compat兼容性标志时node:vmStub 会自动启用。其依赖链条为nodejs_compat 标志启用 compatibility_date 2025-10-01 node:vm Stub 自动可用之所以以nodejs_compat为前提是因为node:vm属于 Node.js 兼容体系的一部分。nodejs_compat标志负责在 Workers Runtime 中开启整套 Node.js API而enable_nodejs_vm_module这类子标志则进一步控制其中某一具体模块的生效时机。2.2 标志的三态行为结合 nodejs-compat.mdx 与 compatibility-flags.mdx 中的机制描述该标志的实际行为可用下表概括场景node:vmStub 是否可用未启用nodejs_compat否整个 Node.js 兼容层未开启启用nodejs_compatcompatibility_date2025-10-01否除非手动加enable_nodejs_vm_module启用nodejs_compatcompatibility_date2025-10-01是自动启用已自动启用但显式添加disable_nodejs_vm_module否手动降级保持旧行为这里体现了 Cloudflare 兼容性标志体系的通用设计标志通常有一个按日期默认开启的节点开发者既可以用compatibility_date整体前移来批量采纳新行为也可以单独用 enable/disable 标志在该日期之前提前启用、或在该日期之后回退禁用。三、实际配置操作指南3.1 通过 Wrangler 配置文件wrangler.jsonc / wrangler.toml兼容性标志在 Worker 的 Wrangler 配置文件中通过compatibility_flags数组声明。以下示例先设定一个早于2025-10-01的compatibility_date再显式加入enable_nodejs_vm_module从而提前启用node:vmStub{ // 兼容日期设为 2025-09-01此时 node:vm 尚未默认启用 compatibility_date: 2025-09-01, // 开启 Node.js 兼容层 compatibility_flags: [ nodejs_compat, // 提前启用 node:vm 模块 Stub enable_nodejs_vm_module ] }反过来如果希望回退默认行为例如某个依赖包在探测到node:vm后走了错误的分支逻辑则保留默认日期但追加禁用标志{ // 兼容日期为 2025-10-01 或之后node:vm 默认启用 compatibility_date: 2025-10-01, compatibility_flags: [ nodejs_compat, // 显式禁用让 node:vm 保持不可导入 disable_nodejs_vm_module ] }值得对照的是本仓库自身的 wrangler.jsonc 就是一个真实示例其compatibility_date为2025-06-02compatibility_flags中只声明了nodejs_compat。由于2025-06-02早于2025-10-01在当前配置下node:vmStub不会被自动启用——这正是日期未到则需手动开启的直观印证。3.2 通过 Cloudflare Dashboard在 Cloudflare Dashboard 中进入对应 Worker 的Settings → General → Compatibility flags兼容性标志区域即可在已有的nodejs_compat基础上追加或移除enable_nodejs_vm_module/disable_nodejs_vm_module。Dashboard 中修改的标志会写入 Worker 配置效果与 Wrangler 一致。3.3 通过 Cloudflare API使用 Workers Script API 或 Workers Versions API 上传 Worker 时兼容性标志需要放在请求体metadata字段的compatibility_flags数组中例如{ metadata: { compatibility_date: 2025-09-01, compatibility_flags: [nodejs_compat, enable_nodejs_vm_module] } }关于三种配置入口Wrangler / Dashboard / API的完整说明可参考 compatibility-flags.mdx。四、仓库源码层的实现佐证4.1 标志数据的 Schema 定义本仓库为所有兼容性标志定义了统一的数据结构校验见 src/schemas/compatibility-flags.ts。enable_nodejs_vm_module文档 Frontmatter 中的字段与该 Schema 一一对应export const compatibilityFlagsSchema z.object({ name: z.string(), enable_date: z.string().optional().nullable(), enable_flag: z.string().nullable(), disable_flag: z.string().optional().nullable(), sort_date: z.string(), experimental: z.boolean().optional(), });可以看出每个标志的核心元数据就是启用标志名 禁用标志名 默认启用日期三要素enable_nodejs_vm_module正是这套机制下的标准产物。4.2 机器可读的 JSON 输出仓库通过 compatibility-flags.json.ts 将src/content/compatibility-flags目录下所有标志文档聚合成一个按sort_date排序的 JSON 列表供前端渲染与自动化工具消费。该端点会读取每个文档的 Frontmatter 与正文描述输出包含enable_flag、disable_flag、enable_date等字段的结构化数据——这意味着node:vm模块标志的状态信息可以通过该接口程序化获取。4.3 Stub 模块总表仓库将各类 Node.js Stub 模块的启用日期与标志集中维护在 nodejs-compat-stub-modules.mdx 中node:vm位于该表第二行Stub 模块随nodejs_compat自动启用的日期启用标志禁用标志node:http22025-09-01enable_nodejs_http2_moduledisable_nodejs_http2_modulenode:vm2025-10-01enable_nodejs_vm_moduledisable_nodejs_vm_modulenode:cluster2025-12-04enable_nodejs_cluster_moduledisable_nodejs_cluster_modulenode:domain2025-12-04enable_nodejs_domain_moduledisable_nodejs_domain_modulenode:trace_events2025-12-04enable_nodejs_trace_events_moduledisable_nodejs_trace_events_modulenode:wasi2025-12-04enable_nodejs_wasi_moduledisable_nodejs_wasi_modulenode:_stream_wrap2026-01-29enable_nodejs_stream_wrap_moduledisable_nodejs_stream_wrap_modulenode:dgram2026-01-29enable_nodejs_dgram_moduledisable_nodejs_dgram_modulenode:inspector2026-01-29enable_nodejs_inspector_moduledisable_nodejs_inspector_modulenode:sqlite2026-01-29enable_nodejs_sqlite_moduledisable_nodejs_sqlite_modulenode:child_process2026-03-17enable_nodejs_child_process_moduledisable_nodejs_child_process_modulenode:readline2026-03-17enable_nodejs_readline_moduledisable_nodejs_readline_modulenode:repl2026-03-17enable_nodejs_repl_moduledisable_nodejs_repl_modulenode:tty2026-03-17enable_nodejs_tty_moduledisable_nodejs_tty_modulenode:v82026-03-17enable_nodejs_v8_moduledisable_nodejs_v8_modulenode:worker_threads2026-03-17enable_nodejs_worker_threads_moduledisable_nodejs_worker_threads_module这张表清楚地展示了同类模块的启用节奏node:vm在2025-10-01加入属于较早一批 Stub 化模块之一。五、Node.js 兼容体系的宏观背景为了正确使用该标志还需要理解它所在的nodejs_compat体系开启入口nodejs_compat标志负责在 Workers Runtime 中启用 Node.js API具体支持范围见 Node.js 运行时 API 文档。本仓库自身的 wrangler.jsonc 即声明了compatibility_flags: [nodejs_compat]。未来默认开启根据 nodejs-compat.mdx对2026-08-04及之后的兼容日期Workers 会默认同时启用nodejs_compat与nodejs_compat_v2无需再显式声明这两个标志届时node:vm等 Stub 模块仍遵循各自的按日期启用规则。日期是开关总闸正如 compatibility-dates.mdx 所解释的指定compatibility_date可以一次性采纳该日期之前的所有兼容性变更。将日期前移到2025-10-01之后node:vmStub 就会随nodejs_compat自动就位。六、最佳实践与注意事项不要把 Stub 当真实 API 使用。node:vmStub 仅为模块存在性探测提供占位不提供可工作的 VM 执行能力。如果业务确实需要代码沙箱执行应寻找 Workers 原生的替代方案而不是依赖node:vm。优先升级兼容日期而非手写标志。Cloudflare 官方建议使用最新版 Wrangler CLI 与最新兼容日期以最大化 Node.js 兼容性较新日期下运行时已内置所需 polyfill无需旧版 Wrangler 额外注入。npm 包加载报错时先检查日期。当某个包因缺少node:vm而报Module not found或Cannot find module node:vm时先确认两件事是否已启用nodejs_compat以及compatibility_date是否达到2025-10-01。未达则通过enable_nodejs_vm_module提前开启或直接前移兼容日期。回退需显式禁用。如果升级日期后某个包反而因检测到node:vm走了错误分支可添加disable_nodejs_vm_module单独回退该模块而不影响其余 Node.js API。善用机器可读清单。可通过 compatibility-flags.json.ts 生成的 JSON 接口程序化比对各标志的启用日期与启停标志辅助自动化排查。七、小结enable_nodejs_vm_module是 Cloudflare Workers Node.js 兼容层中一个典型的按日期默认启用、可单独启停的细粒度标志。它确保node:vm模块以非功能 Stub 的形式在 Workers 中可导入从而保证依赖该模块存在性的 npm 包能够正常工作同时把真实的 VM API 排除在无服务器运行时之外。理解它的启用日期2025-10-01、前置条件nodejs_compat与三种配置入口Wrangler / Dashboard / API是排查相关模块加载问题、安全演进兼容日期的基础能力。相关权威细节均可回溯到本仓库的 enable-nodejs-vm-module.md、nodejs-compat.mdx 与 nodejs-compat-stub-modules.mdx。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
