Cloudflare Pages 是一个用于全栈 Web 应用程序的边缘平台。它不仅能够提供静态文件，还能通过 Cloudflare Workers 提供动态内容。

Hono 完全支持 Cloudflare Pages。这为开发者带来了愉悦的开发体验。Vite 的开发服务器非常快，而使用 Wrangler 部署也极其迅速。

1. 设置

Cloudflare Pages 提供了一个入门模板。你可以通过 “create-hono” 命令来启动你的项目。在这个例子中，选择 cloudflare-pages 模板。

# [npm]
npm create hono@latest my-app


# [yarn]
yarn create hono my-app


# [pnpm]
pnpm create hono my-app


# [bun]
bunx create-hono my-app


# [deno]
deno run -A npm:create-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
│   └── static // 放置你的静态文件。
│       └── style.css // 你可以通过 `/static/style.css` 访问它。
├── src
│   ├── index.tsx // 服务器端的入口点。
│   └── renderer.tsx
├── tsconfig.json
└── vite.config.ts

2. Hello World

将 src/index.tsx 编辑为如下所示：

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

const app = new Hono()

app.get('*', renderer)

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

export default app

3. 运行

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

# [npm]
npm run dev


# [yarn]
yarn dev


# [pnpm]
pnpm dev


# [bun]
bun run dev

4. 部署

如果你有 Cloudflare 账号，可以将项目部署到 Cloudflare。在 package.json 中，需要将 $npm_execpath 修改为你选择的包管理器。

# [npm]
npm run deploy


# [yarn]
yarn deploy


# [pnpm]
pnpm run deploy


# [bun]
bun run deploy

通过 Cloudflare 仪表板与 GitHub 部署

  1. 登录 Cloudflare 仪表板 并选择你的账号。
  2. 在“账户首页”中，选择“Workers & Pages > 创建应用程序 > Pages > 连接到 Git”。
  3. 授权你的 GitHub 账号，并选择仓库。在“设置构建和部署”中，提供以下信息：

配置选项

值

生产分支

main

构建命令

npm run build

构建目录

dist

Bindings

你可以使用 Cloudflare 的 Bindings，比如 Variables、KV、D1 等等。在本节中，我们将使用 Variables 和 KV。

创建 wrangler.toml

首先，为本地 Bindings 创建 wrangler.toml 文件：

touch wrangler.toml

编辑 wrangler.toml，为变量指定名称 MY_NAME。

[vars]
MY_NAME = "Hono"

创建 KV

接下来，创建 KV。运行以下 wrangler 命令：

wrangler kv:namespace create MY_KV --preview

记下 preview_id，它会在输出中显示，如下所示：

{ binding = "MY_KV", preview_id = "abcdef" }

在 Bindings 中为 MY_KV 指定 preview_id：

[[kv_namespaces]]
binding = "MY_KV"
id = "abcdef"

编辑 vite.config.ts

编辑 vite.config.ts 文件：

import devServer from '@hono/vite-dev-server'
import adapter from '@hono/vite-dev-server/cloudflare'
import build from '@hono/vite-cloudflare-pages'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    devServer({
      entry: 'src/index.tsx',
      adapter, // Cloudflare 适配器
    }),
    build(),
  ],
})

在应用中使用 Bindings

在你的应用中使用 Variables 和 KV。首先设置类型。

type Bindings = {
  MY_NAME: string
  MY_KV: KVNamespace
}

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

然后使用它们：

app.get('/', async (c) => {
  await c.env.MY_KV.put('name', c.env.MY_NAME)
  const name = await c.env.MY_KV.get('name')
  return c.render(<h1>Hello! {name}</h1>)
})

在生产环境中

对于 Cloudflare Pages，你将在本地开发中使用 wrangler.toml，但在生产环境中，你需要在仪表板中设置 Bindings。

客户端脚本

你可以编写客户端脚本，并使用 Vite 的功能将它们导入到应用中。如果 /src/client.ts 是客户端的入口点，可以简单地在 script 标签中引入它。此外，import.meta.env.PROD 对于检测是在开发服务器上运行还是在构建阶段非常有用。

app.get('/', (c) => {
  return c.html(
    <html>
      <head>
        {import.meta.env.PROD ? (
          <script type='module' src='/static/client.js'></script>
        ) : (
          <script type='module' src='/src/client.ts'></script>
        )}
      </head>
      <body>
        <h1>Hello</h1>
      </body>
    </html>
  )
})

为了正确构建脚本，你可以使用如下所示的 vite.config.ts 配置文件示例。

import pages from '@hono/vite-cloudflare-pages'
import devServer from '@hono/vite-dev-server'
import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => {
  if (mode === 'client') {
    return {
      build: {
        rollupOptions: {
          input: './src/client.ts',
          output: {
            entryFileNames: 'static/client.js',
          },
        },
      },
    }
  } else {
    return {
      plugins: [
        pages(),
        devServer({
          entry: 'src/index.tsx',
        }),
      ],
    }
  }
})

你可以运行以下命令来构建服务器和客户端脚本。

vite build --mode client && vite build

Cloudflare Pages 中间件

Cloudflare Pages 使用其自有的 中间件 系统，这与 Hono 的中间件不同。你可以通过在名为 _middleware.ts 的文件中导出 onRequest 来启用它，例如：

// functions/_middleware.ts
export async function onRequest(pagesContext) {
  console.log(`你正在访问 ${pagesContext.request.url}`)
  return await pagesContext.next()
}

使用 handleMiddleware，你可以将 Hono 的中间件用作 Cloudflare Pages 的中间件。

// functions/_middleware.ts
import { handleMiddleware } from 'hono/cloudflare-pages'

export const onRequest = handleMiddleware(async (c, next) => {
  console.log(`你正在访问 ${c.req.url}`)
  await next()
})

你还可以使用 Hono 的内置中间件和第三方中间件。例如，要添加基本身份验证，你可以使用 Hono 的 Basic Authentication 中间件。

// functions/_middleware.ts
import { handleMiddleware } from 'hono/cloudflare-pages'
import { basicAuth } from 'hono/basic-auth'

export const onRequest = handleMiddleware(
  basicAuth({
    username: 'hono',
    password: 'acoolproject',
  })
)

如果你想应用多个中间件，可以像这样编写：

import { handleMiddleware } from 'hono/cloudflare-pages'

// ...

export const onRequest = [
  handleMiddleware(middleware1),
  handleMiddleware(middleware2),
  handleMiddleware(middleware3),
]