使用 Hono 在 Cloudflare Workers 上运行 React

Hono 是一个轻量、超快速的 Web 框架，设计用于在包括 Cloudflare Workers、Deno Deploy、Bun 和 Node.js 在内的边缘运行时上运行。它的接口受 Express 启发，但从底层开始便针对 Web 标准（Fetch 接口、Request/Response）构建，因此非常适合边缘环境。

为 Cloudflare Workers 搭建新的 Hono 项目很简单：npm create hono@latest 会提示您选择模板，选择 "cloudflare-workers"，然后创建一个预先配置好 wrangler（Cloudflare 的 CLI）和 Hono 依赖项的项目。

要在 Hono Worker 中对 React 执行服务器端渲染，请安装 react、react-dom 和 @types/react，然后从 react-dom/server 导入 renderToReadableStream。此函数属于 React 18 的流式接口，专为支持 Web Streams 接口的环境设计，而 Cloudflare Workers 正支持该接口。

典型的 SSR 路由处理程序会使用根 React 组件调用 renderToReadableStream，等待流准备就绪，然后使用 c.body(stream, { headers: { 'Content-Type': 'text/html' } }) 或 c.html(htmlString) 发送响应。该流会生成 HTML 片段，浏览器可以逐步渲染这些片段。

renderToReadableStream 返回一个 Promise，解析为包含 HTML 片段的 ReadableStream。此 ReadableStream 符合 Web Streams 接口，可直接作为 Response 对象的正文传入，因此非常适合 Cloudflare Workers 的 fetch 处理程序。

React 流会生成组件树的 HTML，但不会生成外围文档。您必须将该流注入 HTML 外壳：一个包含文档类型声明、带有元标签和 CSS 链接的 head、开始 body 标签的字符串——然后是 React 流，最后是结束 body 和 html 标签。

一个由 Vite 构建的 React 客户端包需要与 Worker 一起提供。Cloudflare Pages 或 Workers Assets 功能可以处理这一点：c.env.ASSETS.fetch(request) 会将资源请求路由到随 Worker 部署一起上传的静态文件。

Worker 入口文件导出一个带有 fetch 处理程序的默认对象：export default { fetch: app.fetch }。Hono 的 app.fetch 方法本身就是兼容的 fetch 处理程序，它接收 Request 并返回 Response，因此可以直接接入 Workers 运行时。

wrangler dev 会在您的计算机上启动一个模拟 Cloudflare Workers 运行时的本地开发服务器。它会监视文件更改并自动重新加载，从而在部署到生产环境之前提供快速的本地开发循环。

wrangler deploy 会将 Worker 代码打包并上传到 Cloudflare 网络，使其在几秒内在全部 300 多个边缘位置上线。wrangler.toml 配置文件会指定您的账户 ID、Worker 名称，以及任何 KV 命名空间或 D1 数据库绑定。

要实现客户端交互，请将 bootstrapScripts: ['/assets/client.js'] 传入 renderToReadableStream。React 会将脚本标签注入 HTML，加载客户端代码包并在服务器渲染的 DOM 上调用 hydrateRoot，使页面在 JS 加载后变得可交互。

renderToReadableStream 返回什么？

Hono 提供轻量、原生支持边缘环境的 HTTP 框架，与 React 的 renderToReadableStream 无缝集成。Worker 入口直接将 app.fetch 导出到 Workers 运行时，静态资源通过 ASSETS 绑定提供，而 wrangler 同时处理本地开发和生产部署。bootstrapScripts 将流式 HTML 连接到客户端水合代码包。