Cloudflare 页面

¥Cloudflare Pages

Cloudflare 页面是全栈 Web 应用的边缘平台。它提供由 Cloudflare Workers 提供的静态文件和动态内容。

¥Cloudflare Pages is an edge platform for full-stack web applications. It serves static files and dynamic content provided by Cloudflare Workers.

Hono 完全支持 Cloudflare Pages。它带来了令人愉悦的开发者体验。Vite 的开发服务器速度很快，使用 Wrangler 部署速度超快。

¥Hono fully supports Cloudflare Pages. It introduces a delightful developer experience. Vite's dev server is fast, and deploying with Wrangler is super quick.

1. 设置

¥ Setup

Cloudflare Pages 的入门程序可用。使用 "create-hono" 命令启动你的项目。为此示例选择 cloudflare-pages 模板。

¥A starter for Cloudflare Pages is available. Start your project with "create-hono" command. Select cloudflare-pages 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
│   └── static // Put your static files.
│       └── style.css // You can refer to it as `/static/style.css`.
├── src
│   ├── index.tsx // The entry point for server-side.
│   └── renderer.tsx
├── tsconfig.json
└── vite.config.ts

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.get('*', renderer)

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

export default app

3. 运行

¥ Run

在本地运行开发服务器。然后，在你的 Web 浏览器中访问 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. 部署

¥ Deploy

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

¥If you have a Cloudflare account, you can deploy to Cloudflare. In package.json, $npm_execpath needs to be changed to your package manager of choice.

npmyarnpnpmbun

npm run deploy

yarn deploy

pnpm run deploy

bun run deploy

通过 Cloudflare 仪表板使用 GitHub 部署

¥Deploy via the Cloudflare dashboard with GitHub

登录 Cloudflare 仪表板并选择你的账户。
¥Log in to the Cloudflare dashboard and select your account.
在 Account Home 中，选择 Workers & Pages > Create application > Pages > Connect to Git。
¥In Account Home, select Workers & Pages > Create application > Pages > Connect to Git.
授权你的 GitHub 账户，然后选择存储库。在设置构建和部署中，提供以下信息：
¥Authorize your GitHub account, and select the repository. In Set up builds and deployments, provide the following information:

配置选项	值
生产分支	`main`
构建命令	`npm run build`
构建目录	`dist`

绑定

¥Bindings

你可以使用 Cloudflare 绑定，如变量、KV、D1 等。在本节中，让我们使用变量和 KV。

¥You can use Cloudflare Bindings like Variables, KV, D1, and others. In this section, let's use Variables and KV.

创建 `wrangler.toml`

¥Create wrangler.toml

首先，为本地绑定创建 wrangler.toml：

¥First, create wrangler.toml for local Bindings:

touch wrangler.toml

编辑 wrangler.toml。使用名称 MY_NAME 指定变量。

¥Edit wrangler.toml. Specify Variable with the name MY_NAME.

toml

[vars]
MY_NAME = "Hono"

创建 KV

¥Create KV

接下来，制作 KV。运行以下 wrangler 命令：

¥Next, make the KV. Run the following wrangler command:

wrangler kv namespace create MY_KV --preview

记下 preview_id 作为以下输出：

¥Note down the preview_id as the following output:

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

使用 Bindings、MY_KV 的名称指定 preview_id：

¥Specify preview_id with the name of Bindings, MY_KV:

toml

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

编辑 `vite.config.ts`

¥Edit vite.config.ts

编辑 vite.config.ts：

¥Edit the 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 Adapter
    }),
    build(),
  ],
})

在你的应用中使用绑定

¥Use Bindings in your application

在你的应用中使用 Variable 和 KV。设置类型。

¥Use Variable and KV in your application. Set the types.

type Bindings = {
  MY_NAME: string
  MY_KV: KVNamespace
}

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

使用它们：

¥Use them:

tsx

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>)
})

在生产中

¥In production

对于 Cloudflare Pages，你将使用 wrangler.toml 进行本地开发，但对于生产，你将在仪表板中设置绑定。

¥For Cloudflare Pages, you will use wrangler.toml for local development, but for production, you will set up Bindings in the dashboard.

客户端

¥Client-side

你可以编写客户端脚本并使用 Vite 的功能将其导入你的应用。如果 /src/client.ts 是客户端的入口点，只需将其写入脚本标记中即可。此外，import.meta.env.PROD 对于检测它是在开发服务器上运行还是在构建阶段运行很有用。

¥You can write client-side scripts and import them into your application using Vite's features. If /src/client.ts is the entry point for the client, simply write it in the script tag. Additionally, import.meta.env.PROD is useful for detecting whether it's running on a dev server or in the build phase.

tsx

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，如下所示。

¥In order to build the script properly, you can use the example config file vite.config.ts as shown below.

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',
        }),
      ],
    }
  }
})

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

¥You can run the following command to build the server and client script.

vite build --mode client && vite build

Cloudflare 页面中间件

¥Cloudflare Pages Middleware

Cloudflare Pages 使用自己的中间件系统，与 Hono 的中间件不同。你可以通过将 onRequest 导出到名为 _middleware.ts 的文件中来启用它，如下所示：

¥Cloudflare Pages uses its own middleware system that is different from Hono's middleware. You can enable it by exporting onRequest in a file named _middleware.ts like this:

// functions/_middleware.ts
export async function onRequest(pagesContext) {
  console.log(`You are accessing ${pagesContext.request.url}`)
  return await pagesContext.next()
}

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

¥Using handleMiddleware, you can use Hono's middleware as Cloudflare Pages middleware.

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

export const onRequest = handleMiddleware(async (c, next) => {
  console.log(`You are accessing ${c.req.url}`)
  await next()
})

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

¥You can also use built-in and 3rd party middleware for Hono. For example, to add Basic Authentication, you can use Hono's Basic Authentication Middleware.

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

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

如果要应用多个中间件，可以这样写：

¥If you want to apply multiple middleware, you can write it like this:

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

// ...

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

访问 `EventContext`

¥Accessing EventContext

你可以通过 handleMiddleware 中的 c.env 访问 EventContext 对象。

¥You can access EventContext object via c.env in handleMiddleware.

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

export const onRequest = [
  handleMiddleware(async (c, next) => {
    c.env.eventContext.data.user = 'Joe'
    await next()
  }),
]

然后，你可以通过处理程序中的 c.env.eventContext 访问数据值：

¥Then, you can access the data value in via c.env.eventContext in the handler:

// functions/api/[[route]].ts
import type { EventContext } from 'hono/cloudflare-pages'
import { handle } from 'hono/cloudflare-pages'

// ...

type Env = {
  Bindings: {
    eventContext: EventContext
  }
}

const app = new Hono<Env>().basePath('/api')

app.get('/hello', (c) => {
  return c.json({
    message: `Hello, ${c.env.eventContext.data.user}!`, // 'Joe'
  })
})

export const onRequest = handle(app)

Cloudflare 页面 ​

1. 设置 ​

2. Hello World ​

3. 运行 ​

4. 部署 ​

通过 Cloudflare 仪表板使用 GitHub 部署 ​

绑定 ​

创建 wrangler.toml ​

创建 KV ​

编辑 vite.config.ts ​

在你的应用中使用绑定 ​

在生产中 ​

客户端 ​

Cloudflare 页面中间件 ​

访问 EventContext ​

Cloudflare 页面

1. 设置

2. Hello World

3. 运行

4. 部署

通过 Cloudflare 仪表板使用 GitHub 部署

绑定

创建 `wrangler.toml`

创建 KV

编辑 `vite.config.ts`

在你的应用中使用绑定

在生产中

客户端

Cloudflare 页面中间件

访问 `EventContext`