企业官网建设流程全解析

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_compat，node:http、node:https等模块才可能被加载。而针对 HTTP 模块，Cloudflare 又进一步拆成了两个互补的标志：

本指南聚焦后者：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 API：

• http.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 启用时间表中也有对应记录：

2.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()等客户端请求 API；
• enable_nodejs_http_server_modules启用的是createServer()、Server、ServerResponse等服务端API。

一个典型 Worker 通常既是客户端（向外发起 fetch/HTTP 请求）又是服务端（响应访客请求），因此实践中往往同时依赖这两个标志。兼容日期未达 2025-09-01 的存量项目，需要手动同时声明这两个标志；兼容日期在 2025-09-01 之后的项目则随nodejs_compat自动获得完整能力。

三、实战：在 Worker 中配置并运行 Node.js HTTP Server

3.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 的EventEmitter）：

import { 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.mdx，Workers 的服务端实现存在以下差异，迁移既有代码时需逐项核对：

5.1 请求（IncomingMessage/req）

• Trailer 头不支持；
• req.socket不继承自net.Socket，只包含encrypted、remoteFamily、remoteAddress、remotePort、localAddress、localPort以及destroy()方法；
• socket部分属性行为与 Node.js 不同：
  • remoteAddress：本地运行时返回127.0.0.1；
  • remotePort：返回 2^15 到 2^16 之间的随机端口号；
  • localAddress：返回请求host头的值；不存在时返回127.0.0.1；
  • localPort：返回分配给服务器实例的端口号；
  • req.socket.destroy()会回退到req.destroy()。

5.2 服务器（Server）

• closeAllConnections()、closeIdleConnections()等连接管理方法未实现；
• listen()仅支持带端口号或不带参数的变体，如listen()、listen(0, callback)、listen(callback)，不支持 host、Unix socket、path 等参数；
• 以下 server 选项不支持：maxHeaderSize、insecureHTTPParser、keepAliveTimeout、connectionsCheckingInterval。

5.3 响应（ServerResponse）

• assignSocket()、detachSocket()方法不可用；
• Trailer 头不支持；
• writeContinue()、writeEarlyHints()方法不可用，整体上不支持 1xx 响应。

5.4 生命周期注意事项

原文档特别提醒：如果未调用close()，HTTP 服务器会一直存活到 Worker 销毁。绝大多数场景下服务器本就应伴随 Worker 生命周期，这不是问题；但如果需要在 Worker 存活期内创建多个服务器，或希望显式控制生命周期（例如测试场景），务必在使用完毕后调用close()，或使用 V8 显式资源管理（explicit resource management） 特性。

六、兼容日期时间线小结

综合本文涉及的三个文档，Node.js HTTP 能力的演进时间线如下：

1. 2025-08-15：enable_nodejs_http_modules自动启用，node:http/node:https的客户端 API 可用；
2. 2025-09-01：enable_nodejs_http_server_modules自动启用，createServer()、Server、ServerResponse服务端 API 可用；
3. 2026-08-04（nodejs-compat.mdx 中说明）：兼容日期等于或晚于该日期的 Worker，nodejs_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