H3
基于 Web 标准、面向现代 JavaScript 运行时的轻量高性能 HTTP 框架。
项目概述
H3 是 UnJS 生态中的极简服务端框架，以 Request、Response、URL 和 Headers 等 Web 标准为基础，在保持小巧可组合的同时支持路由、中间件、错误处理和跨运行时部署。
H3（读作 h-three）将 HTTP 服务抽象建立在 Web 标准之上，应用可以通过同一套 fetch 兼容接口运行在 Node.js、Deno、Bun 和边缘运行时。它只提供精简核心，路由、Cookie、缓存、会话与验证等能力通过可摇树优化的工具按需引入。H3 也是 Nitro 与 Nuxt 服务端能力的重要基础，但可以独立用于 API、微服务和框架底层。当前官方主文档面向 H3 v2，旧版 v1 项目升级时需要参考迁移指南。
主要特点
H3 用很薄的抽象统一路由、请求处理与响应生成，并让扩展能力保持显式、可组合。
基于 Web 标准
请求、响应、Headers、URL 和流均采用标准 Web API，减少平台专属概念并提升运行时可移植性。
轻量可组合核心
从小型 H3 实例开始，只导入实际使用的工具，让服务体积、初始化成本和全局副作用保持可控。
内置高效路由
通过 Rou3 匹配静态、参数与通配路由，并提供 get、post、all、mount 等清晰的注册方式。
灵活的 Event Handler
处理器可同步或异步返回对象、字符串、流或标准 Response，H3 会完成规范化和错误处理。
跨运行时 Fetch 接口
app.fetch 可直接适配 Web 兼容运行时，app.request 则能在不监听端口的情况下调用路由和编写测试。
中间件与生命周期钩子
可在请求、响应和错误阶段加入认证、日志、上下文与观测逻辑，也能为单个处理器组合中间件。
应用挂载与互操作
支持挂载子级 H3 应用或其他 fetch 兼容处理器，便于拆分模块、渐进迁移和组合不同框架。
类型友好的工具集
以 TypeScript 编写，并提供请求解析、Cookie、缓存、会话、代理和流式响应等按需工具。
适用场景
适合重视体积、启动速度、跨运行时能力，或需要构建上层服务端框架的 TypeScript 项目。
轻量 JSON API
快速构建类型友好的 REST 风格接口、Webhook 接收器和面向前端的 Backend for Frontend。
边缘与 Serverless 函数
标准 fetch 边界适合部署到支持 Web API 的边缘平台和按请求启动的无服务器环境。
跨运行时服务
同一套应用逻辑可面向 Node.js、Deno、Bun 等环境，减少因迁移运行时而改写业务处理器的成本。
框架和平台底层
适合作为全栈框架、开发服务器、API 网关或内部平台的 HTTP 路由与处理基础。
微服务与内部接口
较少的内置约束便于为单一领域服务组合认证、数据库、缓存和观测方案。
渐进式系统迁移
可挂载 fetch 兼容应用，也能在 Node 环境包装传统处理器，适合逐步替换旧服务。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
H3 擅长的地方
- 核心小巧，工具按需导入并利于摇树优化
- 采用 Web 标准，跨运行时部署和互操作边界清晰
- 处理器可以直接返回普通值或标准 Response，开发体验简洁
- app.request 与 app.fetch 让无端口测试和平台适配更直接
- 路由、中间件、子应用与生命周期能力足以支撑常见 API
- 与 Nitro、Nuxt 和 UnJS 工具生态衔接自然
需要注意
采用前应考虑的问题
当前官方主文档已转向 v2，但发布与 API 仍可能继续调整；生产采用前应锁定版本并阅读变更记录。
createApp、createRouter、defineEventHandler 等常见 v1 写法在 v2 已迁移或更名，搜索示例时要先确认文档版本。
数据库、Schema 验证、依赖注入、任务队列和完整项目结构不由核心统一规定，团队需要制定约定。
文件系统、TCP、Node 专属包和平台绑定仍存在差异，关键路径必须在目标运行时实际测试。
fromNodeHandler 便于迁移传统中间件，但依赖 req、res 或 Node API 的代码无法直接运行在所有边缘环境。
WebSocket 支持依赖 CrossWS 且官方仍标注为进行中；实时项目应先验证目标适配器、连接生命周期和平台限制。
快速开始
使用 H3 v2 创建带参数校验、错误响应和无监听测试的最小 JSON API。
bashmkdir hello-h3
cd hello-h3
npm init -y
npm install h3typescriptimport { H3, HTTPError } from "h3";
export const app = new H3()
.get("/", () => ({ name: "H3", status: "ok" }))
.get("/api/hello/:name", (event) => {
const name = event.context.params?.name?.trim();
if (!name) {
throw new HTTPError({
status: 400,
message: "Name is required",
});
}
return {
message: `Hello, ${name}!`,
runtime: globalThis.process?.release?.name ?? "web",
};
});typescriptimport { serve } from "h3";
import { app } from "./app.mjs";
serve(app, { port: 3000 });bashnode --watch server.mjs
# 访问接口
curl http://localhost:3000/api/hello/Docs100typescriptimport assert from "node:assert/strict";
import test from "node:test";
import { app } from "./app.mjs";
test("returns a greeting", async () => {
const response = await app.request("/api/hello/H3");
const body = await response.json();
assert.equal(response.status, 200);
assert.equal(body.message, "Hello, H3!");
});下一步：先围绕标准 Request、Response 和 app.fetch 建立边界；生产环境再补充输入 Schema、统一错误格式、日志、限流与运行时适配测试。
类似项目
这些 TypeScript 服务端框架同样强调轻量、现代 API 或多运行时部署。
H3 vs Hono
H3 和 Hono 都是基于 Web 标准、适配多种 JavaScript 运行时的轻量框架；H3 更贴近 UnJS 与 Nitro 的可组合服务端基础，Hono 则提供更完整的应用 API、中间件目录与类型化路由体验。
| 比较维度 | H3 | Hono |
|---|---|---|
| 核心定位 | 可组合的极简 HTTP 框架与上层框架基础 | 面向应用开发的轻量多运行时 Web 框架 |
| 请求模型 | H3Event 封装标准 Request、Response 与上下文 | Context 封装请求、响应、变量与执行环境 |
| 路由风格 | H3 实例方法、处理器和子应用挂载 | 链式路由、路由分组和 RPC 类型推断 |
| 类型体验 | 处理器与工具类型完善，客户端契约需另行设计 | 强调路由 Schema、验证器和类型化客户端 RPC |
| 扩展生态 | UnJS 工具、Nitro 与 Nuxt 服务端生态 | 官方中间件、适配器、JSX 与辅助工具覆盖更广 |
| 测试方式 | app.request 可直接调用任意路由 | app.request 可构造请求并断言响应 |
| 更适合 | UnJS 项目、框架底层和极简可组合服务 | 希望快速获得完整 Web API 开发体验的团队 |
如果项目使用 Nuxt、Nitro 或希望以最小核心搭建自定义服务端抽象，H3 通常更自然；如果需要大量现成中间件、路由级验证和端到端 RPC 类型体验，Hono 往往更直接。两者都适合 Web 标准运行时，最终应以目标平台、依赖生态和真实负载测试决定。
资料核验
版本、维护信息与本页采用的官方资料来源。
本次核验覆盖 H3 的核心定位、主要能力、官方入口与开源许可。项目版本持续更新，具体补丁版本、兼容性和迁移要求请在采用前继续核对官方发布记录。
官方仓库未归档，核验时最近可见的代码活动日期为 2026 年 7 月 24 日。该状态表示项目近期仍有公开维护活动，不代表固定发布频率或长期支持承诺。