# Cloudflare Workers 部署

URL: https://caijiao.org/hono/05-deploy/02-cloudflare-workers
Source: docs/hono/05-deploy/02-cloudflare-workers.md
Description: 学习 Hono 在 Cloudflare Workers 中的项目创建、wrangler 配置、Bindings、静态资源和部署流程。

Cloudflare Workers 是 Hono 最常见的部署目标之一。它运行在边缘网络上，使用 Fetch API 模型，与 Hono 的设计非常契合。

## 创建 Workers 项目

```bash
pnpm create hono@latest my-worker -- --template cloudflare-workers
cd my-worker
pnpm install
pnpm dev
```

开发服务器通常运行在 `http://localhost:8787`。

## 基本入口

```ts
import { Hono } from 'hono'

const app = new Hono()

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

export default app
```

如果需要同时导出其他事件处理器，例如定时任务，可以使用对象形式：

```ts
const app = new Hono()

export default {
  fetch: app.fetch,
  scheduled: async (event, env, ctx) => {
    console.log('scheduled task')
  },
}
```

## wrangler 配置

```jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-hono-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-29",
  "vars": {
    "APP_NAME": "Hono API"
  }
}
```

环境变量通过 `c.env` 读取：

```ts
type Bindings = {
  APP_NAME: string
}

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

app.get('/info', (c) => {
  return c.json({ name: c.env.APP_NAME })
})
```

## 静态资源

Workers 可以配置静态资源目录：

```jsonc
{
  "assets": {
    "directory": "public"
  }
}
```

把资源放在 `public/` 下：

```text
public/
├─ favicon.ico
└─ static/
   └─ hello.txt
```

静态资源由平台服务，Hono 继续处理动态路由。

## 部署

```bash
pnpm deploy
```

或者直接使用 Wrangler：

```bash
pnpm wrangler deploy
```

部署前确认：

- 已登录 Cloudflare 账号。
- `wrangler.jsonc` 中的 `name`、`main`、`compatibility_date` 正确。
- Secret 已通过 Wrangler 或控制台配置。
- D1、KV、R2 等绑定名称和代码里的 `Bindings` 一致。

## Workers 注意事项

- 不要依赖长期驻留内存。实例可能被回收。
- 不要默认使用 `process.env`，优先使用 `c.env`。
- 数据库连接方式要适配边缘环境，避免传统长连接池不兼容。
- CPU 时间、请求体大小、子请求数量等限制要提前查看平台文档。

Hono 让 Workers API 写起来像普通 Web 服务，但部署模型仍然是边缘函数，设计时要尊重平台限制。