Hono + TypeScript 后端项目搭建完整笔记Hono + TypeScript 项目搭建完整笔记目录一、

Hono + TypeScript 项目搭建完整笔记

用 Hono 框架 + TypeScript 从 0 搭建一个 Node.js 后端项目的完整流程。包括环境配置、项目初始化、第一个接口、GitHub 仓库管理。

一、技术栈选型

工具	作用	为什么选
Node.js 20+	JavaScript 运行时	LTS 版本,支持 `--env-file` 等新特性
TypeScript	类型系统	后端必备,保证类型安全
Hono	HTTP 框架	比 Express 更现代、更轻、性能更好,语法接近 Web 标准
pnpm	包管理器	比 npm 快、省磁盘空间(硬链接)
tsx	TS 运行器	开发期直接跑 .ts,无需编译

Hono vs Express 对比

维度	Express	Hono
类型支持	弱(需手动定义)	原生 TS,类型推导强
运行环境	仅 Node	Node / Bun / Deno / Cloudflare Workers
API 风格	Callback / Promise	基于 Web Fetch 标准
体积	较大	轻量(0 依赖)
生态	老牌、丰富	新兴、增长快

结论:新项目 TS 后端,Hono 是 2026 年的默认选择之一。

二、环境准备

1. 检查环境

node --version    # 需要 >= 20
git --version
brew --version    # Mac 推荐用 Homebrew 管理工具

2. 装 pnpm

brew install pnpm
pnpm --version

3. 项目目录建议

cd ~
mkdir -p code        # 或者你习惯的位置
cd code
mkdir my-project
cd my-project

三、项目初始化

1. 初始化 package.json

pnpm init

生成基础 package.json,稍后会改 scripts 部分。

2. 装核心依赖

# 运行时依赖
pnpm add hono @hono/node-server

# 开发依赖
pnpm add -D typescript @types/node tsx

说明:

hono — 框架本体
@hono/node-server — Hono 跑在 Node 上的适配器(Hono 本身可以跑很多环境)
typescript — TS 编译器
@types/node — Node API 的类型定义
tsx — 直接跑 .ts 文件的工具(开发期用,无需 build)

3. 初始化 TypeScript 配置

pnpm tsc --init

生成 tsconfig.json。默认配置够用,无需修改。

4. 项目目录结构

my-project/
├── src/
│   └── index.ts          # 入口文件
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
└── .gitignore

mkdir src
touch src/index.ts

四、第一个 Hono 应用

1. 最小可运行代码

// src/index.ts
import { Hono } from 'hono'
import { serve } from '@hono/node-server'

const app = new Hono()

app.get('/', (c) => {
  return c.json({
    name: 'my-project',
    version: '0.1.0',
    message: 'Hello from Hono'
  })
})

app.get('/health', (c) => {
  return c.json({
    status: 'ok',
    timestamp: new Date().toISOString()
  })
})

const port = 3000
serve({
  fetch: app.fetch,
  port
})

console.log(`Server running on http://localhost:${port}`)

2. Hono 核心 API 速览

API	用途
`new Hono()`	创建应用实例
`app.get(path, handler)`	注册 GET 路由
`app.post(path, handler)`	注册 POST 路由
`app.put / delete / patch`	其他 HTTP 方法
`app.use(middleware)`	注册中间件
`c.json(data)`	返回 JSON
`c.text(str)`	返回纯文本
`c.req.param('id')`	获取 URL 参数
`c.req.query('q')`	获取 query 参数
`c.req.json()`	解析 JSON body

3. Context 对象(c)

每个 handler 接收一个 c(Context),封装了请求和响应:

app.get('/users/:id', (c) => {
  const id = c.req.param('id')              // URL 参数
  const search = c.req.query('search')      // query
  const auth = c.req.header('Authorization') // header
  
  return c.json({ id, search }, 200)        // 第二个参数是 HTTP 状态码
})

五、开发模式与脚本

1. 配置 `package.json` scripts

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "start": "tsx src/index.ts"
  }
}

说明:

dev — watch 模式,文件改了自动重启(开发期用)
start — 单次启动(生产或测试时用)

2. 启动开发服务

pnpm dev

应该看到:

Server running on http://localhost:3000

3. 测试接口

# 浏览器或 curl
curl http://localhost:3000/
curl http://localhost:3000/health

4. 文件改动自动重启

tsx watch 监听文件变化,改保存后自动重启进程。等同于 nodemon。

六、Git 与 GitHub 配置

1. 初始化 Git

git init

2. 必备 `.gitignore`

# 依赖
node_modules/

# 编辑器
.DS_Store
.vscode/
.idea/

# 环境变量
.env
.env.local

# 日志
*.log

# 构建产物
dist/
build/

关键:.env 和 node_modules/ 必须忽略。

.env — 会包含密码、API key,推上 GitHub 等于公开
node_modules/ — 体积巨大且可重新安装

3. 第一次 commit

git add .
git status              # 检查准备提交的文件
git commit -m "feat: initial project setup with Hono"

4. Conventional Commits 规范

推荐 commit message 用约定式前缀:

前缀	用途	示例
`feat:`	新功能	`feat: add health check endpoint`
`fix:`	修 bug	`fix: resolve cors issue`
`docs:`	文档变更	`docs: update README`
`chore:`	杂事(依赖更新等)	`chore: bump hono to v4.x`
`refactor:`	重构	`refactor: extract route handlers`
`test:`	测试相关	`test: add unit tests for routes`
`style:`	格式化(无逻辑)	`style: format code with prettier`

参考:www.conventionalcommits.org/

5. 推到 GitHub

# 1. GitHub 网页:创建 Public 仓库
#    (注意:不要勾选 Initialize with README,本地已经有了)

# 2. 关联远程仓库
git remote add origin https://github.com/your-id/my-project.git
git branch -M main
git push -u origin main

6. README 模板

# my-project

> 项目简介

## 技术栈

- TypeScript
- Hono
- Node.js 20+

## 快速开始

```bash
pnpm install
pnpm dev
```

访问 http://localhost:3000

## 接口

| 方法 | 路径 | 描述 |
|---|---|---|
| GET | / | Hello world |
| GET | /health | 健康检查 |

## License

MIT

七、关键概念

1. 为什么不用 Bun?

Bun 是更激进的替代品(运行时 + 包管理 + 打包器),性能更快。

维度	Node + tsx	Bun
稳定性	成熟	还在快速演进
生态兼容	完美	部分包不兼容
启动速度	较快	极快
团队接受度	标配	仍在普及

结论:新手或团队项目用 Node + tsx 稳妥;个人项目想尝鲜可以试 Bun。

2. 为什么 `pnpm` 而不是 `npm` / `yarn`

项	npm	yarn	pnpm
安装速度	慢	中	快
磁盘占用	每项目独立 node_modules	同上	全局硬链接,省 50%+ 空间
严格依赖	松散	松散	严格(只能访问声明的依赖)
主流度	默认	老牌	新兴主流

2026 年的 TS 项目,pnpm 是默认推荐。

3. `tsx` vs `ts-node` vs `tsc`

工具	用途
`tsc`	TS 编译器,把 .ts 编译成 .js(生产用)
`ts-node`	老牌 TS 直接运行器(基于 tsc)
`tsx`	新一代 TS 运行器,基于 esbuild,速度快 10 倍

开发期:用 tsx(快、watch 模式好用) 生产期:用 tsc 编译后 node dist/index.js(或直接用 tsx)

4. HTTP 状态码常用速查

码	含义	用法
200	OK	成功响应
201	Created	POST 创建成功
204	No Content	成功但没有返回数据(常用于 DELETE)
400	Bad Request	请求参数错误
401	Unauthorized	未登录
403	Forbidden	已登录但无权限
404	Not Found	资源不存在
409	Conflict	资源冲突(如重复创建)
500	Internal Server Error	服务器错误

5. RESTful 路径设计原则

GET    /users          # 列表
POST   /users          # 创建
GET    /users/:id      # 详情
PUT    /users/:id      # 全量更新
PATCH  /users/:id      # 部分更新
DELETE /users/:id      # 删除

复数名词 + HTTP 动词 表达资源操作。

八、参考资源

Hono 官方文档:hono.dev
TypeScript 文档:www.typescriptlang.org/docs/
pnpm 文档:pnpm.io/
Conventional Commits:www.conventionalcommits.org/

下一篇笔记会涵盖:Zod 输入验证 / 中间件 / 错误处理 / RESTful 路由设计。

Hono + TypeScript 后端项目搭建完整笔记