入门指南（Getting Started）

使用 Hono 非常简单。我们可以快速完成项目搭建、写代码、用本地服务器开发并进行部署。相同的代码可以在任意运行时（runtime）运行，只是入口文件略有不同。下面我们来看一下 Hono 的基础用法。

Starter（启动模板）

每个平台都有可用的 Starter 模板。使用下面的 create-hono 命令即可创建项目。

npm

  1. npm create hono@latest my-app

yarn

  1. yarn create hono my-app

pnpm

  1. pnpm create hono@latest my-app

bun

  1. bun create hono@latest my-app

deno

  1. deno init --npm hono@latest my-app

接着你会被询问想要使用哪个模板。这里我们选择 Cloudflare Workers。

  1. ? Which template do you want to use?
  2.     aws-lambda
  3.     bun
  4.     cloudflare-pages
  5. ❯   cloudflare-workers
  6.     deno
  7.     fastly
  8.     nextjs
  9.     nodejs
  10.     vercel

模板会被下载到 my-app 目录下，进入该目录并安装依赖。

npm

  1. cd my-app
  2. npm i

yarn

  1. cd my-app
  2. yarn

pnpm

  1. cd my-app
  2. pnpm i

bun

  1. cd my-app
  2. bun i

依赖安装完成后，运行以下命令启动本地服务器。

npm

  1. npm run dev

yarn

  1. yarn dev

pnpm

  1. pnpm dev

bun

  1. bun run dev

Hello World

你可以直接用 TypeScript 编写代码，通过 Cloudflare Workers 的开发工具 Wrangler、Deno、Bun 或其他工具运行，而无需关注转译。

在 src/index.ts 中写出你的第一个 Hono 应用。下面是一个 Hono 的基础示例。

import 和 export default 的写法会因运行时（runtime）不同而略有差别，但应用的业务代码在所有环境中都是通用的。

  1. import { Hono } from 'hono'
  3. const app = new Hono()
  5. app.get('/', (c) => {
  6.   return c.text('Hello Hono!')
  7. })
  9. export default app

启动开发服务器后，用浏览器访问 http://localhost:8787。

npm

  1. npm run dev

yarn

  1. yarn dev

pnpm

  1. pnpm dev

bun

  1. bun run dev

返回 JSON

返回 JSON 也非常简单。下面是一个处理 GET 请求 /api/hello 并返回 application/json 的例子。

  1. app.get('/api/hello', (c) => {
  2.   return c.json({
  3.     ok: true,
  4.     message: 'Hello Hono!',
  5.   })
  6. })

Request 和 Response

获取路径参数、URL 查询参数并添加 Response Header 的写法如下：

  1. app.get('/posts/:id', (c) => {
  2.   const page = c.req.query('page')
  3.   const id = c.req.param('id')
  4.   c.header('X-Message', 'Hi!')
  5.   return c.text(`You want to see ${page} of ${id}`)
  6. })

我们不仅能轻松处理 GET，还能处理 POST、PUT 和 DELETE。

  1. app.post('/posts', (c) => c.text('Created!', 201))
  2. app.delete('/posts/:id', (c) =>
  3.   c.text(`${c.req.param('id')} is deleted!`)
  4. )

返回 HTML

你可以用 html Helper 或 JSX 语法生成 HTML。 如果想用 JSX，请将文件名改为 src/index.tsx 并根据运行时进行配置（各环境配置不同）。下面是一个 JSX 示例：

  1. const View = () => {
  2.   return (
  3.     <html>
  4.       <body>
  5.         <h1>Hello Hono!</h1>
  6.       </body>
  7.     </html>
  8.   )
  9. }
  11. app.get('/page', (c) => {
  12.   return c.html(<View />)
  13. })

返回原生 Response

你也可以直接返回原生 Response。

  1. app.get('/', () => {
  2.   return new Response('Good morning!')
  3. })

使用 Middleware

Middleware 可以帮你处理复杂任务。比如添加 Basic Authentication：

  1. import { basicAuth } from 'hono/basic-auth'
  3. // ...
  5. app.use(
  6.   '/admin/*',
  7.   basicAuth({
  8.     username: 'admin',
  9.     password: 'secret',
  10.   })
  11. )
  13. app.get('/admin', (c) => {
  14.   return c.text('You are authorized!')
  15. })

Hono 内置了包括 Bearer、JWT 鉴权、CORS 和 ETag 在内的多种常用 middleware。它还提供了第三方 middleware，如 GraphQL Server、Firebase Auth 等。同时你也可以编写自己的 middleware。

Adapter（适配器）

对于一些平台相关的功能（比如静态文件处理、WebSocket），可以使用 Adapter。 例如，在 Cloudflare Workers 中处理 WebSocket，只需引入 hono/cloudflare-workers。

  1. import { upgradeWebSocket } from 'hono/cloudflare-workers'
  3. app.get(
  4.   '/ws',
  5.   upgradeWebSocket((c) => {
  6.     // ...
  7.   })
  8. )

下一步

大部分代码可以在任何平台上运行，但项目配置和部署方式会因平台而异。 请查看你所需平台的文档以了解具体的搭建和部署步骤！