入门指南

¥Getting Started

开始使用 H3。

¥Get started with H3.

概览

¥Overview

⚡ H3（H(TTP) 的缩写，发音为 /eɪtʃθriː/，类似于 h-3）是一个轻量级、快速且可组合的现代 JavaScript 运行时服务器框架。它基于 Web 标准原语，例如 请求、响应、URL 和 标头。你可以将 H3 与任何兼容的运行时或 mount 等 Web 兼容的处理程序集成到 H3，几乎不会增加延迟。

¥⚡ H3 (short for H(TTP), pronounced as /eɪtʃθriː/, like h-3) is a lightweight, fast, and composable server framework for modern JavaScript runtimes. It is based on web standard primitives such as Request, Response, URL, and Headers. You can integrate H3 with any compatible runtime or mount other web-compatible handlers to H3 with almost no added latency.

H3 的设计目标是可扩展和可组合。无需提供一个大型核心，你可以从一个轻量级 H3 实例 开始，然后导入内置的、可摇树优化的 utilities，或者使用你自己的 utilities 来获得更多功能。可组合实用程序具有以下几个优点：

¥H3 is designed to be extendable and composable. Instead of providing one big core, you start with a lightweight H3 instance and then import built-in, tree-shakable utilities or bring your own for more functionality. Composable utilities has several advantages:

• 服务器仅包含已使用的代码，并在需要的地方准确运行它们。
• 应用规模可以更好地扩展。实用函数的使用清晰明确，全局影响较小。
• H3 的自以为是，不会限制你的选择。

所有实用程序共享一个 H3Event 上下文。

¥All utilities, share an H3Event context.

快速入门

¥Quick Start

将 h3 安装为依赖：

¥Install h3 as a dependency:

npm i h3@beta

yarn add h3@beta

pnpm i h3@beta

bun i h3@beta

deno i h3@beta

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

¥Create a new file for server entry:

import { H3, serve } from "h3";

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

serve(app, { port: 3000 });

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

¥Then, run the server using your favorite runtime:

node --watch ./server.mjs

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

bun run --watch server.mjs

然后，tadaa！我们在本地运行一个 Web 服务器。

¥And tadaa! We have a web server running locally.

发生了什么？

¥What Happened?

好的，现在让我们分解一下我们的 hello world 示例。

¥Okay, let's now break down our hello world example.

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

¥We first created an H3 app instance using new H3():

const app = new H3();

H3 是一个小型类，能够实现 匹配路由、生成响应 以及调用 中间件 和 全局钩子。

¥H3 is a tiny class capable of matching routes, generating responses and calling middleware and global hooks.

然后，我们添加了一条路由，用于处理指向 / 路径的 HTTP GET 请求。

¥Then we add a route for handling HTTP GET requests to / path.

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

我们只是返回一个对象。H3 自动将 converts 值转换为 Web 响应。

¥We simply returned an object. H3 automatically converts values into web responses.

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

¥Finally, we use serve method to start the server listener. Using serve method you can easily start an H3 server in various runtimes.

serve(app, { port: 3000 });

我们还有 app.fetch，它可以直接用于在任何兼容 Web 的运行时中运行 H3 应用，甚至可以直接用于测试目的。

¥We also have app.fetch which can be directly used to run H3 apps in any web-compatible runtime or even directly called for testing purposes.

import { H3, serve } from "h3";

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

// Test without listening
const response = await app.fetch("/");
console.log(await response.text());

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

¥You can directly import h3 library from CDN alternatively. This method can be used for Bun, Deno and other runtimes such as Cloudflare Workers.

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

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

export const fetch = app.fetch;