菜鸟教程
教程 hono tutorial

Cloudflare Workers 部署

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 服务，但部署模型仍然是边缘函数，设计时要尊重平台限制。

相关内容