Cloudflare Workers 启用 Node.js HTTP Server 模块enable_nodejs_http_server_modules兼容性标志深度指南【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本篇指南以 Cloudflare Docs 仓库中的兼容性标志文档 enable-nodejs-http-server-modules.md 为核心系统讲解enable_nodejs_http_server_modules标志的作用、与enable_nodejs_http_modules的搭配关系、自动启用的兼容日期规则并结合仓库内 Node.js Runtime API 文档 给出可复制的http.createServer()/http.Server/http.ServerResponse实战示例。读完本文你将掌握如何在 Workers 中跑起标准 Node.js HTTP 服务端代码并了解它与本地 Node.js 环境的差异与限制。一、背景Workers 的 Node.js 兼容性体系Cloudflare Workers 运行时本身并不直接运行 Node.js而是通过一组「兼容性标志Compatibility Flags」逐步开放 Node.js API。这些标志统一声明在 src/content/compatibility-flags 目录下每个标志一个 Markdown 文档包含enable_flag、disable_flag、enable_date等 frontmatter 元数据。其中总开关是 nodejs-compat.mdx 定义的nodejs_compat标志。只有先启用了nodejs_compatnode:http、node:https等模块才可能被加载。而针对 HTTP 模块Cloudflare 又进一步拆成了两个互补的标志标志启用 API 范围自动启用日期enable_nodejs_http_modulesnode:http/node:https的客户端 API发起请求2025-08-15enable_nodejs_http_server_modulesnode:http的服务端 API接收请求、创建服务器2025-09-01本指南聚焦后者enable_nodejs_http_server_modules。二、enable_nodejs_http_server_modules标志详解2.1 标志声明该标志在仓库中对应文档 enable-nodejs-http-server-modules.md其 frontmatter 声明如下name: Enable Node.js HTTP server modules sort_date: 2025-09-01 enable_date: 2025-09-01 enable_flag: enable_nodejs_http_server_modules disable_flag: disable_nodejs_http_server_modules这意味着该标志对应的两个 CLI/配置项是成对出现的enable_nodejs_http_server_modules启用 Node.js HTTP 服务端模块如node:_http_server在 Workers 中的可用性disable_nodejs_http_server_modules显式禁用这些服务端模块。2.2 启用后获得的功能根据原文档启用该标志后node:http的服务端能力将包含以下标准 Node.js APIhttp.createServer()创建 HTTP 服务器的工厂函数http.Server类表示服务器实例负责监听并分发传入请求http.ServerResponse服务端响应对象用于处理并写出响应内容。这些正是 Node.js 标准库node:http中面向「接收请求、返回响应」一侧的核心 API因此凡是依赖这些 API 的既有 Node.js 代码与 npm 库都可以直接迁入 Workers 运行。2.3 自动启用规则兼容日期原文档明确了一条关键规则当 Worker 的兼容日期compatibility date为 2025-09-01 或之后、且启用了nodejs_compat时该标志会被自动启用。也就是说对于新项目只要把compatibility_date设置到2025-09-01之后并开启nodejs_compat就无需手动书写enable_nodejs_http_server_modules该行为在 nodejs-compat.mdx 的 Node.js API 启用时间表中也有对应记录Node.js API随nodejs_compat启用的兼容日期node:http、node:https客户端 API2025-08-15http.server服务端 API2025-09-012.4 与enable_nodejs_http_modules的搭配关系原文档特别强调一个易被忽略的前提该标志必须与enable_nodejs_http_modules标志组合使用才能启用node:http的完整功能。原因在于两者覆盖的 API 面向完全不同enable_nodejs_http_modules见 enable-nodejs-http-modules.md启用的是http.request()、https.request()、http.get()、https.get()等客户端请求 APIenable_nodejs_http_server_modules启用的是createServer()、Server、ServerResponse等服务端API。一个典型 Worker 通常既是客户端向外发起 fetch/HTTP 请求又是服务端响应访客请求因此实践中往往同时依赖这两个标志。兼容日期未达 2025-09-01 的存量项目需要手动同时声明这两个标志兼容日期在 2025-09-01 之后的项目则随nodejs_compat自动获得完整能力。三、实战在 Worker 中配置并运行 Node.js HTTP Server3.1 配置 wrangler.jsonc以本仓库自身的 Worker 配置 wrangler.jsonc 为参照启用nodejs_compat的方式如下{ name: my-worker, compatibility_date: 2025-09-15, compatibility_flags: [nodejs_compat], main: ./src/index.js }这里compatibility_date已经晚于 2025-09-01因此enable_nodejs_http_server_modules会自动生效无需显式书写。如果你的兼容日期早于 2025-09-01则需要手动追加{ compatibility_date: 2025-08-01, compatibility_flags: [nodejs_compat, enable_nodejs_http_modules, enable_nodejs_http_server_modules] }提示nodejs_compat文档nodejs-compat.mdx建议使用最新版 Wrangler CLI 与最新的兼容日期以最大化兼容性——较新兼容日期下运行时已内置原本需要 Wrangler 注入的 polyfill。3.2 最小可运行示例http.createServer参照 Node.js Runtime API 文档 中的示例下面是一个完整的 Worker使用 Node.js 风格创建 HTTP 服务器import { createServer } from node:http; import { httpServerHandler } from cloudflare:node; const server createServer((req, res) { res.writeHead(200, { Content-Type: text/plain }); res.end(Hello from Node.js HTTP server!); }); server.listen(8080); export default httpServerHandler({ port: 8080 });关键点createServer()返回的server以 Node.js 惯例处理(req, res)回调server.listen(8080)中的端口在 Workers 环境中并不真正占用网络端口而是作为路由键详见下文httpServerHandler负责把 Workers 的请求模型桥接到 Node.js 服务器上。3.3 使用http.Server类除了工厂函数也可以直接用Server类它继承自 Node.js 的EventEmitterimport { Server } from node:http; import { httpServerHandler } from cloudflare:node; const server new Server((req, res) { res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ message: Hello from HTTP Server! })); }); server.listen(8080); export default httpServerHandler({ port: 8080 });3.4 使用http.ServerResponse处理响应ServerResponse继承自 Node.js 的Writable流支持流式写出响应体import { createServer, ServerResponse } from node:http; import { httpServerHandler } from cloudflare:node; import { ok } from node:assert; const server createServer((req, res) { ok(res instanceof ServerResponse); // 一次设置多个响应头 res.writeHead(200, { Content-Type: application/json, X-Custom-Header: Workers-HTTP, }); // 流式写出响应数据 res.write({data: [); res.write({id: 1, name: Item 1},); res.write({id: 2, name: Item 2}); res.write(]}); // 结束响应 res.end(); }); export default httpServerHandler(server);这里同时演示了httpServerHandler的两种调用方式既可以直接传入 server 实例也可以传入{ port }对象。四、从源码文档看实现原理请求如何路由到 Node.js 服务器Workers 运行时没有真实的 TCP 监听端口node:http的服务端实现实际是对全局fetchAPI 的一层封装http.mdx 中明确指出node:http的实现是 a wrapper around the globalfetchAPI。因此 Cloudflare 提供了两个桥接函数4.1httpServerHandler—— 一键桥接httpServerHandler来自cloudflare:node模块自动把传入的 Worker 请求路由到你的 Node.js 服务器。它支持两种模式import http from node:http; import { httpServerHandler } from cloudflare:node; const server http.createServer((req, res) { res.end(hello world); }); // 模式一直接传 server必要时会自动调用 listen() export default httpServerHandler(server); // 模式二基于端口路由可容纳多个服务器 server.listen(8080); export default httpServerHandler({ port: 8080 });在端口路由模式下server.listen()的端口号并非真实的网络端口而是一个路由键httpServerHandler依据该端口决定把请求交给哪个服务器实例。因此同一个 Worker 内可以用不同端口号并存多个 HTTP 服务器。若使用端口值0或null、undefined则会分配一个随机端口。4.2handleAsNodeRequest—— 精细控制路由如果需要完全掌控fetch处理器可以直接把请求转交给指定端口的 Node.js 服务器import { createServer } from node:http; import { handleAsNodeRequest } from cloudflare:node; const server createServer((req, res) { res.writeHead(200, { Content-Type: text/plain }); res.end(Hello from Node.js HTTP server!); }); server.listen(8080); export default { fetch(request) { return handleAsNodeRequest(8080, request); }, };4.3 访问 Cloudflare 专属请求属性在 Node.js 请求回调中req.cloudflare.cf暴露了 Cloudflare 专属的请求属性与 Workers 原生Request的cf一致例如import { createServer } from node:http; import { httpServerHandler } from cloudflare:node; const server createServer((req, res) { console.log(req.cloudflare.cf.country); console.log(req.cloudflare.cf.ray); res.write(Hello, World!); res.end(); }); server.listen(8080); export default httpServerHandler({ port: 8080 });五、与标准 Node.js 的差异与限制务必知悉依据 http.mdxWorkers 的服务端实现存在以下差异迁移既有代码时需逐项核对5.1 请求IncomingMessage/reqTrailer 头不支持req.socket不继承自net.Socket只包含encrypted、remoteFamily、remoteAddress、remotePort、localAddress、localPort以及destroy()方法socket部分属性行为与 Node.js 不同remoteAddress本地运行时返回127.0.0.1remotePort返回 2^15 到 2^16 之间的随机端口号localAddress返回请求host头的值不存在时返回127.0.0.1localPort返回分配给服务器实例的端口号req.socket.destroy()会回退到req.destroy()。5.2 服务器ServercloseAllConnections()、closeIdleConnections()等连接管理方法未实现listen()仅支持带端口号或不带参数的变体如listen()、listen(0, callback)、listen(callback)不支持 host、Unix socket、path 等参数以下 server 选项不支持maxHeaderSize、insecureHTTPParser、keepAliveTimeout、connectionsCheckingInterval。5.3 响应ServerResponseassignSocket()、detachSocket()方法不可用Trailer 头不支持writeContinue()、writeEarlyHints()方法不可用整体上不支持 1xx 响应。5.4 生命周期注意事项原文档特别提醒如果未调用close()HTTP 服务器会一直存活到 Worker 销毁。绝大多数场景下服务器本就应伴随 Worker 生命周期这不是问题但如果需要在 Worker 存活期内创建多个服务器或希望显式控制生命周期例如测试场景务必在使用完毕后调用close()或使用 V8 显式资源管理explicit resource management 特性。六、兼容日期时间线小结综合本文涉及的三个文档Node.js HTTP 能力的演进时间线如下2025-08-15enable_nodejs_http_modules自动启用node:http/node:https的客户端 API 可用2025-09-01enable_nodejs_http_server_modules自动启用createServer()、Server、ServerResponse服务端 API 可用2026-08-04nodejs-compat.mdx 中说明兼容日期等于或晚于该日期的 Workernodejs_compat与nodejs_compat_v2默认同时启用无需再写这两个标志。七、迁移建议新项目直接把compatibility_date设为2025-09-01之后建议用最新稳定日期并启用nodejs_compat即可同时获得客户端与服务端两套node:http能力存量项目若兼容日期较早请在compatibility_flags中显式添加enable_nodejs_http_modules与enable_nodejs_http_server_modules两个标志遇到 npm 包报错优先尝试更新兼容日期并升级 Wrangler CLI若仍存在问题可在 workers-sdk 仓库 的 GitHub Issue 中反馈nodejs-compat.mdx提供了官方反馈入口想要完全关闭 Node.js 兼容性移除nodejs_compat与nodejs_compat_v2若存在并添加no_nodejs_compat与no_nodejs_compat_v2。通过本文的配置与代码示例你可以将既有的 Node.js HTTP 服务端代码直接迁移到 Cloudflare Workers同时利用req.cloudflare.cf获得 Cloudflare 网络的专属能力实现「Node.js 开发体验 Workers 全球分发」的组合。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare Workers 启用 Node.js HTTP Server 模块enable_nodejs_http_server_modules兼容性标志深度指南【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本篇指南以 Cloudflare Docs 仓库中的兼容性标志文档 enable-nodejs-http-server-modules.md 为核心系统讲解enable_nodejs_http_server_modules标志的作用、与enable_nodejs_http_modules的搭配关系、自动启用的兼容日期规则并结合仓库内 Node.js Runtime API 文档 给出可复制的http.createServer()/http.Server/http.ServerResponse实战示例。读完本文你将掌握如何在 Workers 中跑起标准 Node.js HTTP 服务端代码并了解它与本地 Node.js 环境的差异与限制。一、背景Workers 的 Node.js 兼容性体系Cloudflare Workers 运行时本身并不直接运行 Node.js而是通过一组「兼容性标志Compatibility Flags」逐步开放 Node.js API。这些标志统一声明在 src/content/compatibility-flags 目录下每个标志一个 Markdown 文档包含enable_flag、disable_flag、enable_date等 frontmatter 元数据。其中总开关是 nodejs-compat.mdx 定义的nodejs_compat标志。只有先启用了nodejs_compatnode:http、node:https等模块才可能被加载。而针对 HTTP 模块Cloudflare 又进一步拆成了两个互补的标志标志启用 API 范围自动启用日期enable_nodejs_http_modulesnode:http/node:https的客户端 API发起请求2025-08-15enable_nodejs_http_server_modulesnode:http的服务端 API接收请求、创建服务器2025-09-01本指南聚焦后者enable_nodejs_http_server_modules。二、enable_nodejs_http_server_modules标志详解2.1 标志声明该标志在仓库中对应文档 enable-nodejs-http-server-modules.md其 frontmatter 声明如下name: Enable Node.js HTTP server modules sort_date: 2025-09-01 enable_date: 2025-09-01 enable_flag: enable_nodejs_http_server_modules disable_flag: disable_nodejs_http_server_modules这意味着该标志对应的两个 CLI/配置项是成对出现的enable_nodejs_http_server_modules启用 Node.js HTTP 服务端模块如node:_http_server在 Workers 中的可用性disable_nodejs_http_server_modules显式禁用这些服务端模块。2.2 启用后获得的功能根据原文档启用该标志后node:http的服务端能力将包含以下标准 Node.js APIhttp.createServer()创建 HTTP 服务器的工厂函数http.Server类表示服务器实例负责监听并分发传入请求http.ServerResponse服务端响应对象用于处理并写出响应内容。这些正是 Node.js 标准库node:http中面向「接收请求、返回响应」一侧的核心 API因此凡是依赖这些 API 的既有 Node.js 代码与 npm 库都可以直接迁入 Workers 运行。2.3 自动启用规则兼容日期原文档明确了一条关键规则当 Worker 的兼容日期compatibility date为 2025-09-01 或之后、且启用了nodejs_compat时该标志会被自动启用。也就是说对于新项目只要把compatibility_date设置到2025-09-01之后并开启nodejs_compat就无需手动书写enable_nodejs_http_server_modules该行为在 nodejs-compat.mdx 的 Node.js API 启用时间表中也有对应记录Node.js API随nodejs_compat启用的兼容日期node:http、node:https客户端 API2025-08-15http.server服务端 API2025-09-012.4 与enable_nodejs_http_modules的搭配关系原文档特别强调一个易被忽略的前提该标志必须与enable_nodejs_http_modules标志组合使用才能启用node:http的完整功能。原因在于两者覆盖的 API 面向完全不同enable_nodejs_http_modules见 enable-nodejs-http-modules.md启用的是http.request()、https.request()、http.get()、https.get()等客户端请求 APIenable_nodejs_http_server_modules启用的是createServer()、Server、ServerResponse等服务端API。一个典型 Worker 通常既是客户端向外发起 fetch/HTTP 请求又是服务端响应访客请求因此实践中往往同时依赖这两个标志。兼容日期未达 2025-09-01 的存量项目需要手动同时声明这两个标志兼容日期在 2025-09-01 之后的项目则随nodejs_compat自动获得完整能力。三、实战在 Worker 中配置并运行 Node.js HTTP Server3.1 配置 wrangler.jsonc以本仓库自身的 Worker 配置 wrangler.jsonc 为参照启用nodejs_compat的方式如下{ name: my-worker, compatibility_date: 2025-09-15, compatibility_flags: [nodejs_compat], main: ./src/index.js }这里compatibility_date已经晚于 2025-09-01因此enable_nodejs_http_server_modules会自动生效无需显式书写。如果你的兼容日期早于 2025-09-01则需要手动追加{ compatibility_date: 2025-08-01, compatibility_flags: [nodejs_compat, enable_nodejs_http_modules, enable_nodejs_http_server_modules] }提示nodejs_compat文档nodejs-compat.mdx建议使用最新版 Wrangler CLI 与最新的兼容日期以最大化兼容性——较新兼容日期下运行时已内置原本需要 Wrangler 注入的 polyfill。3.2 最小可运行示例http.createServer参照 Node.js Runtime API 文档 中的示例下面是一个完整的 Worker使用 Node.js 风格创建 HTTP 服务器import { createServer } from node:http; import { httpServerHandler } from cloudflare:node; const server createServer((req, res) { res.writeHead(200, { Content-Type: text/plain }); res.end(Hello from Node.js HTTP server!); }); server.listen(8080); export default httpServerHandler({ port: 8080 });关键点createServer()返回的server以 Node.js 惯例处理(req, res)回调server.listen(8080)中的端口在 Workers 环境中并不真正占用网络端口而是作为路由键详见下文httpServerHandler负责把 Workers 的请求模型桥接到 Node.js 服务器上。3.3 使用http.Server类除了工厂函数也可以直接用Server类它继承自 Node.js 的EventEmitterimport { Server } from node:http; import { httpServerHandler } from cloudflare:node; const server new Server((req, res) { res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ message: Hello from HTTP Server! })); }); server.listen(8080); export default httpServerHandler({ port: 8080 });3.4 使用http.ServerResponse处理响应ServerResponse继承自 Node.js 的Writable流支持流式写出响应体import { createServer, ServerResponse } from node:http; import { httpServerHandler } from cloudflare:node; import { ok } from node:assert; const server createServer((req, res) { ok(res instanceof ServerResponse); // 一次设置多个响应头 res.writeHead(200, { Content-Type: application/json, X-Custom-Header: Workers-HTTP, }); // 流式写出响应数据 res.write({data: [); res.write({id: 1, name: Item 1},); res.write({id: 2, name: Item 2}); res.write(]}); // 结束响应 res.end(); }); export default httpServerHandler(server);这里同时演示了httpServerHandler的两种调用方式既可以直接传入 server 实例也可以传入{ port }对象。四、从源码文档看实现原理请求如何路由到 Node.js 服务器Workers 运行时没有真实的 TCP 监听端口node:http的服务端实现实际是对全局fetchAPI 的一层封装http.mdx 中明确指出node:http的实现是 a wrapper around the globalfetchAPI。因此 Cloudflare 提供了两个桥接函数4.1httpServerHandler—— 一键桥接httpServerHandler来自cloudflare:node模块自动把传入的 Worker 请求路由到你的 Node.js 服务器。它支持两种模式import http from node:http; import { httpServerHandler } from cloudflare:node; const server http.createServer((req, res) { res.end(hello world); }); // 模式一直接传 server必要时会自动调用 listen() export default httpServerHandler(server); // 模式二基于端口路由可容纳多个服务器 server.listen(8080); export default httpServerHandler({ port: 8080 });在端口路由模式下server.listen()的端口号并非真实的网络端口而是一个路由键httpServerHandler依据该端口决定把请求交给哪个服务器实例。因此同一个 Worker 内可以用不同端口号并存多个 HTTP 服务器。若使用端口值0或null、undefined则会分配一个随机端口。4.2handleAsNodeRequest—— 精细控制路由如果需要完全掌控fetch处理器可以直接把请求转交给指定端口的 Node.js 服务器import { createServer } from node:http; import { handleAsNodeRequest } from cloudflare:node; const server createServer((req, res) { res.writeHead(200, { Content-Type: text/plain }); res.end(Hello from Node.js HTTP server!); }); server.listen(8080); export default { fetch(request) { return handleAsNodeRequest(8080, request); }, };4.3 访问 Cloudflare 专属请求属性在 Node.js 请求回调中req.cloudflare.cf暴露了 Cloudflare 专属的请求属性与 Workers 原生Request的cf一致例如import { createServer } from node:http; import { httpServerHandler } from cloudflare:node; const server createServer((req, res) { console.log(req.cloudflare.cf.country); console.log(req.cloudflare.cf.ray); res.write(Hello, World!); res.end(); }); server.listen(8080); export default httpServerHandler({ port: 8080 });五、与标准 Node.js 的差异与限制务必知悉依据 http.mdxWorkers 的服务端实现存在以下差异迁移既有代码时需逐项核对5.1 请求IncomingMessage/reqTrailer 头不支持req.socket不继承自net.Socket只包含encrypted、remoteFamily、remoteAddress、remotePort、localAddress、localPort以及destroy()方法socket部分属性行为与 Node.js 不同remoteAddress本地运行时返回127.0.0.1remotePort返回 2^15 到 2^16 之间的随机端口号localAddress返回请求host头的值不存在时返回127.0.0.1localPort返回分配给服务器实例的端口号req.socket.destroy()会回退到req.destroy()。5.2 服务器ServercloseAllConnections()、closeIdleConnections()等连接管理方法未实现listen()仅支持带端口号或不带参数的变体如listen()、listen(0, callback)、listen(callback)不支持 host、Unix socket、path 等参数以下 server 选项不支持maxHeaderSize、insecureHTTPParser、keepAliveTimeout、connectionsCheckingInterval。5.3 响应ServerResponseassignSocket()、detachSocket()方法不可用Trailer 头不支持writeContinue()、writeEarlyHints()方法不可用整体上不支持 1xx 响应。5.4 生命周期注意事项原文档特别提醒如果未调用close()HTTP 服务器会一直存活到 Worker 销毁。绝大多数场景下服务器本就应伴随 Worker 生命周期这不是问题但如果需要在 Worker 存活期内创建多个服务器或希望显式控制生命周期例如测试场景务必在使用完毕后调用close()或使用 V8 显式资源管理explicit resource management 特性。六、兼容日期时间线小结综合本文涉及的三个文档Node.js HTTP 能力的演进时间线如下2025-08-15enable_nodejs_http_modules自动启用node:http/node:https的客户端 API 可用2025-09-01enable_nodejs_http_server_modules自动启用createServer()、Server、ServerResponse服务端 API 可用2026-08-04nodejs-compat.mdx 中说明兼容日期等于或晚于该日期的 Workernodejs_compat与nodejs_compat_v2默认同时启用无需再写这两个标志。七、迁移建议新项目直接把compatibility_date设为2025-09-01之后建议用最新稳定日期并启用nodejs_compat即可同时获得客户端与服务端两套node:http能力存量项目若兼容日期较早请在compatibility_flags中显式添加enable_nodejs_http_modules与enable_nodejs_http_server_modules两个标志遇到 npm 包报错优先尝试更新兼容日期并升级 Wrangler CLI若仍存在问题可在 workers-sdk 仓库 的 GitHub Issue 中反馈nodejs-compat.mdx提供了官方反馈入口想要完全关闭 Node.js 兼容性移除nodejs_compat与nodejs_compat_v2若存在并添加no_nodejs_compat与no_nodejs_compat_v2。通过本文的配置与代码示例你可以将既有的 Node.js HTTP 服务端代码直接迁移到 Cloudflare Workers同时利用req.cloudflare.cf获得 Cloudflare 网络的专属能力实现「Node.js 开发体验 Workers 全球分发」的组合。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
