Cloudflare Workers + Vite

使用 @cloudflare/vite-plugin，可以通过 Vite 在 Cloudflare Workers 上构建全栈应用。 该配置提供快速的 Vite 开发服务器、Hono JSX 渲染器实现的服务端渲染，以及由 Vite 打包的客户端脚本，所有内容都运行在 Cloudflare Workers 上。

这是在 Cloudflare 上创建新全栈项目的推荐方式。

1. 初始化

Cloudflare Workers 与 Vite 有可用的项目模板。 使用「create-hono」命令开始创建项目。 本示例选择 cloudflare-workers+vite 模板。

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono my-app

bun

bun create hono@latest my-app

deno

deno init --npm hono my-app

进入 my-app 并安装依赖。

npm

cd my-app
npm i

yarn

cd my-app
yarn

pnpm

cd my-app
pnpm i

bun

cd my-app
bun i

下面是基本的目录结构。

./
├── package.json
├── public // Put your static files here.
├── src
│   ├── index.tsx // The entry point for server-side.
│   ├── renderer.tsx
│   └── style.css
├── tsconfig.json
├── vite.config.ts
└── wrangler.jsonc

vite.config.ts 将 Cloudflare 插件与 vite-ssr-components 结合，用于 SSR：

import { cloudflare } from '@cloudflare/vite-plugin'
import { defineConfig } from 'vite'
import ssrPlugin from 'vite-ssr-components/plugin'

export default defineConfig({
  plugins: [cloudflare(), ssrPlugin()],
})

2. Hello World

按以下方式编辑 src/index.tsx：

import { Hono } from 'hono'
import { renderer } from './renderer'

const app = new Hono()

app.use(renderer)

app.get('/', (c) => {
  return c.render(<h1>Hello, Cloudflare Workers!</h1>)
})

export default app

renderer 在 src/renderer.tsx 中定义，结合 Hono 的 JSX 渲染器中间件与 vite-ssr-components，后者负责接入 Vite 的客户端和资源：

import { jsxRenderer } from 'hono/jsx-renderer'
import { Link, ViteClient } from 'vite-ssr-components/hono'

export const renderer = jsxRenderer(({ children }) => {
  return (
    <html>
      <head>
        <ViteClient />
        <Link href='/src/style.css' rel='stylesheet' />
      </head>
      <body>{children}</body>
    </html>
  )
})

3. 运行

在本地运行开发服务器，然后在浏览器中访问 http://localhost:5173。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

4. 部署

如果拥有 Cloudflare 账户，就可以部署到 Cloudflare。deploy 脚本先使用 Vite 构建，再使用 Wrangler 发布。

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm run deploy

bun

bun run deploy

绑定

可以使用变量、KV、D1 等 Cloudflare 绑定。 在 wrangler.jsonc 中配置绑定。例如，添加名为 MY_NAME 的变量：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  "compatibility_date": "2025-08-03",
  "main": "./src/index.tsx",
  "vars": {
    "MY_NAME": "Hono",
  },
}

要生成绑定类型，请运行 cf-typegen 脚本：

npm

npm run cf-typegen

yarn

yarn cf-typegen

pnpm

pnpm run cf-typegen

bun

bun run cf-typegen

这会生成 CloudflareBindings 接口，将其作为泛型参数传递给 Hono：

const app = new Hono<{ Bindings: CloudflareBindings }>()

然后通过 c.env 访问绑定：

app.get('/', (c) => {
  return c.render(<h1>Hello! {c.env.MY_NAME}</h1>)
})

客户端

vite-ssr-components 允许你通过 Vite 加载客户端脚本。 添加一个指向客户端入口的 Script 组件，Vite 会负责开发环境和生产环境的打包：

import { jsxRenderer } from 'hono/jsx-renderer'
import { Script, ViteClient } from 'vite-ssr-components/hono'

export const renderer = jsxRenderer(({ children }) => {
  return (
    <html>
      <head>
        <ViteClient />
        <Script src='/src/client.ts' />
      </head>
      <body>{children}</body>
    </html>
  )
})

更多详情请参阅 @cloudflare/vite-plugin 文档和 vite-ssr-components。