入门指南

概览

⚡ H3（简称 H(TTP)，发音为 /eɪtʃθriː/，类似 h-3）是一个轻量、快速、可组合的服务器框架，适用于现代 JavaScript 运行时。它基于网页标准原语，如 Request、Response、URL 和 Headers。你可以将 H3 集成到任何兼容的运行时，或者将其他支持 web 的处理器挂载到 H3，几乎不会带来额外延迟。

H3 设计为可扩展且可组合。它不提供一个庞大的核心，而是从一个轻量的 H3 实例 开始，然后导入内置的、支持摇树优化的 实用工具，或者自定义引入更多功能。 可组合工具拥有多个优点：

• 服务器只包含使用到的代码，并在需要的位置运行。
• 应用体积可更好地扩展。工具使用显式且清晰，减少全局影响。
• H3 采用极简设计，不会限制你的选择。

所有实用工具共享一个 H3Event 上下文。

快速开始

安装 h3 作为依赖：

npm i h3@beta

yarn add h3@beta

pnpm i h3@beta

bun i h3@beta

deno i h3@beta

创建一个新文件作为服务器入口：

import { H3, serve } from "h3";

const app = new H3().get("/", (event) => "⚡️ Tadaa!");

serve(app, { port: 3000 });

然后，使用你喜欢的运行时运行服务器：

node --watch ./server.mjs

deno run -A --watch ./server.mjs

bun run --watch server.mjs

就这样！本地就运行起了一个 Web 服务器。

这发生了什么？

现在，让我们解析一下这个 hello world 示例。

我们首先用 new H3() 创建了一个 H3 应用实例：

const app = new H3();

H3 是一个小型类，具备匹配路由、生成响应和调用中间件及全局钩子的能力。

接着我们添加了一个路由，用于处理 / 路径的 HTTP GET 请求。

app.get("/", (event) => {
  return { message: "⚡️ Tadaa!" };
});

我们直接返回了一个对象。H3 会自动将值转换为网页响应。

最后，我们使用 serve 方法启动服务器监听。利用 serve 方法，你可以轻松地在多种运行时中启动一个 H3 服务器。

serve(app, { port: 3000 });

我们还有 app.fetch，可以直接在任何支持 Web 的运行时中运行 H3 应用，甚至可直接调用进行测试。

import { H3, serve } from "h3";

const app = new H3().get("/", () => "⚡️ Tadaa!");

// 无需监听即可测试
const response = await app.fetch("/");
console.log(await response.text());

你也可以直接从 CDN 导入 h3 库。此方法适用于 Bun、Deno 及 Cloudflare Workers 等其他运行时。

import { H3 } from "https://esm.sh/h3@beta";

const app = new H3().get("/", () => "⚡️ Tadaa!");

export const fetch = app.fetch;