入门

使用 Hono 非常容易。我们可以完成项目搭建、编写代码、在本地服务器上开发并快速部署。相同的代码在任意运行时都能运行，只是入口函数不同。下面就来看一下 Hono 的基础用法。

启动模板

每个平台都有对应的启动模板。使用以下 create-hono 命令即可。

npm create hono@latest my-app

yarn create hono my-app

pnpm create hono@latest my-app

bun create hono@latest my-app

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 目录下，进入该目录并安装依赖。

npmyarnpnpmbun

cd my-app
npm i

cd my-app
yarn

cd my-app
pnpm i

cd my-app
bun i

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

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

Hello World

你可以使用 Cloudflare Workers 的开发工具 Wrangler、Deno、Bun 等环境，直接编写 TypeScript 代码，而无需关心转译。

在 src/index.ts 中编写第一个 Hono 应用。下面的示例是一个最基础的 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。

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

返回 JSON

返回 JSON 也十分简单。下面的示例展示了如何处理 /api/hello 的 GET 请求，并返回 application/json 类型的响应。

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

请求与响应

下面的示例展示了如何获取路径参数、URL 查询参数，并向响应追加 Header。

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。

tsx

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 等。另外还有使用外部库构建的第三方中间件，例如 GraphQL Server、Firebase Auth。当然，你也可以自行编写中间件。

适配器

针对静态文件、WebSocket 等平台相关的功能，Hono 提供了对应的适配器。例如，在 Cloudflare Workers 上处理 WebSocket 时，可以引入 hono/cloudflare-workers。

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

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

下一步

绝大多数代码都能在任何平台上运行，不过每个平台都有相应的指南。例如项目如何配置、如何部署等。请选择你要使用的平台，查看对应的指南继续构建应用吧！

入门 ​

启动模板 ​

Hello World ​

返回 JSON ​

请求与响应 ​

返回 HTML ​

返回原生 Response ​

使用中间件 ​

适配器 ​

下一步 ​

入门

启动模板

Hello World

返回 JSON

请求与响应

返回 HTML

返回原生 Response

使用中间件

适配器

下一步