入门指南

使用 Hono 非常简单。我们可以快速完成项目初始化、编写代码、使用本地服务器开发和部署。同一份代码可以运行在任何运行时上，只需使用不同的入口。下面来了解 Hono 的基本用法。

项目模板

每个平台都有对应的项目模板。使用以下「create-hono」命令。

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono@latest my-app

bun

bun create hono@latest my-app

deno

deno init --npm hono@latest my-app

随后会询问你想使用哪个模板。 本示例选择 Cloudflare Workers。

? Which template do you want to use?
    aws-lambda
    bun
    cloudflare-pages
❯   cloudflare-workers
    deno
    fastly
    nextjs
    nodejs
    vercel

模板会下载到 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

安装完软件包后，运行以下命令启动本地服务器。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

Hello World

使用 Cloudflare Workers 开发工具「Wrangler」、Deno、Bun 等工具时，可以直接编写 TypeScript 代码，无需关注转译过程。

在 src/index.ts 中编写你的第一个 Hono 应用。下面是一个入门示例。

import 和最后的 export default 部分可能因运行时而异， 但应用代码本身在所有环境中都可以保持一致。

import { Hono } from 'hono'

const app = new Hono()

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

export default app

启动开发服务器，并在浏览器中访问 http://localhost:8787。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

返回 JSON

返回 JSON 也很简单。下面的示例处理发送到 /api/hello 的 GET 请求，并返回 application/json 响应。

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

请求和响应

可以按以下方式获取路径参数、URL 查询参数值，并添加响应标头。

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

除了 GET，还可以轻松处理 POST、PUT 和 DELETE。

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

返回 HTML

可以使用 html 辅助函数或 JSX 语法编写 HTML。如果要使用 JSX，请将文件重命名为 src/index.tsx 并进行配置（配置因运行时而异，请查阅对应文档）。下面是一个使用 JSX 的示例。

const View = () => {
  return (
    <html>
      <body>
        <h1>Hello Hono!</h1>
      </body>
    </html>
  )
}

app.get('/page', (c) => {
  return c.html(<View />)
})

返回原生 Response

也可以直接返回原生 Response。

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

使用中间件

中间件可以帮你完成繁琐的工作。 例如，添加基本身份验证。

import { basicAuth } from 'hono/basic-auth'

// ...

app.use(
  '/admin/*',
  basicAuth({
    username: 'admin',
    password: 'secret',
  })
)

app.get('/admin', (c) => {
  return c.text('You are authorized!')
})

Hono 提供了实用的内置中间件，包括 Bearer 和 JWT 身份验证，以及 CORS 和 ETag。 Hono 也提供使用外部库的第三方中间件，例如 GraphQL Server 和 Firebase Auth。 此外，你还可以编写自己的中间件。

适配器

对于处理静态文件或 WebSocket 等平台相关功能，可以使用适配器。 适配器作为独立的软件包发布。例如，要在 Cloudflare Workers 中处理 WebSocket，请安装并导入 @hono/cloudflare-workers。

import { upgradeWebSocket } from '@hono/cloudflare-workers'

app.get(
  '/ws',
  upgradeWebSocket((c) => {
    // ...
  })
)

下一步

大部分代码可以在任何平台上运行，但各个平台也有各自的指南。 例如，介绍如何初始化项目或部署应用。 请查阅你希望用来创建应用的平台对应的页面！