Cloudflare Workers + Vite

你可以使用 @cloudflare/vite-plugin 在 Cloudflare Workers 上结合 Vite 构建一个全栈应用。这种设置为你提供了快速的 Vite 开发服务器，使用 Hono 的 JSX 渲染器进行服务器端渲染，以及由 Vite 打包的客户端脚本——所有这些都运行在 Cloudflare Workers 上。

🌐 You can build a full-stack application on Cloudflare Workers with Vite using the @cloudflare/vite-plugin. This setup gives you a fast Vite dev server, server-side rendering with Hono's JSX renderer, and client-side scripts bundled by Vite — all running on Cloudflare Workers.

这是在 Cloudflare 上开始一个新的全栈项目的推荐方式。

🌐 This is the recommended way to start a new full-stack project on Cloudflare.

1. 设置

🌐 1. Setup

一个用于 Cloudflare Workers 的 Vite 入门模板已可用。使用 "create-hono" 命令启动你的项目。在此示例中选择 cloudflare-workers+vite 模板。

🌐 A starter for Cloudflare Workers with Vite is available. Start your project with the "create-hono" command. Select the cloudflare-workers+vite template for this example.

npm create hono@latest my-app

yarn create hono my-app

pnpm create hono my-app

bun create hono@latest my-app

deno init --npm hono my-app

进入 my-app 并安装依赖。

🌐 Move into my-app and install the dependencies.

npmyarnpnpmbun

cd my-app
npm i

cd my-app
yarn

cd my-app
pnpm i

cd my-app
bun i

下面是一个基本的目录结构。

🌐 Below is a basic directory structure.

text

./
├── 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：

🌐 The vite.config.ts combines the Cloudflare plugin with vite-ssr-components for 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. 你好，世界

🌐 2. Hello World

像下面这样编辑 src/index.tsx：

🌐 Edit src/index.tsx like the following:

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 的客户端和资源连接起来：

🌐 The renderer is defined in src/renderer.tsx using Hono's JSX renderer middleware together with vite-ssr-components, which wires up Vite's client and assets:

tsx

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. 跑

🌐 3. Run

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

🌐 Run the development server locally. Then, access http://localhost:5173 in your web browser.

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

4. 部署

🌐 4. Deploy

如果你有 Cloudflare 账户，你可以部署到 Cloudflare。deploy 脚本使用 Vite 构建，然后用 Wrangler 发布。

🌐 If you have a Cloudflare account, you can deploy to Cloudflare. The deploy script builds with Vite and then publishes with Wrangler.

npmyarnpnpmbun

npm run deploy

yarn deploy

pnpm run deploy

bun run deploy

绑定

🌐 Bindings

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

🌐 You can use Cloudflare Bindings like Variables, KV, D1, and others. Configure them in wrangler.jsonc. For example, to add a Variable named MY_NAME:

jsonc

{
  "$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 脚本：

🌐 To generate the types for your Bindings, run the cf-typegen script:

npmyarnpnpmbun

npm run cf-typegen

yarn cf-typegen

pnpm run cf-typegen

bun run cf-typegen

这将生成一个 CloudflareBindings 接口。将其作为泛型传递给 Hono：

🌐 This generates a CloudflareBindings interface. Pass it to Hono as generics:

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

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

🌐 Then access the Bindings via c.env:

tsx

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

客户端

🌐 Client-side

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

tsx

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。

🌐 For more details, see the @cloudflare/vite-plugin documentation and vite-ssr-components.

Cloudflare Workers + Vite ​

1. 设置 ​

2. 你好，世界 ​

3. 跑 ​

4. 部署 ​

绑定 ​

客户端 ​

Cloudflare Workers + Vite

1. 设置

2. 你好，世界

3. 跑

4. 部署

绑定

客户端