# H3 v2

> 🎉 H3 v2 现已正式稳定！它基于 Web 标准进行了全面重写，与大多数 v1 工具保持兼容，并且比 v1 更快、更精简。

::read-more{to="/guide"}
访问 [**H3 指南**](/guide)开始使用。
::

::read-more{to="/migration"}
正在从 v1 升级？请阅读[**迁移指南**](/migration)。
::

```js
import { H3, serve } from "h3";

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

serve(app, { port: 3000 });
```

## 🌐 优先采用 Web 标准

H3 v2 基于 [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request)、[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)、[URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) 和 [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) 构建。处理程序接收 `event.req`（标准的 `Request`）和 `event.url`，并通过 `event.res` 设置响应头。

可以返回任意值（string、object、`Response`、stream、`Blob` 等），H3 会将其转换为 `Response`。

```js
import { defineHandler } from "h3";

const handler = defineHandler(async (event) => {
  const { pathname, searchParams } = event.url;
  const accept = event.req.headers.get("Accept");
  const body = await event.req.json();

  event.res.headers.set("x-powered-by", "h3");
  return { hello: "web" };
});
```

:read-more{to="/guide/basics/handler" title="事件处理器"}

## 🚀 随处运行

同一个应用可运行在 Node.js、Bun、Deno、Cloudflare Workers、Service Workers 和浏览器中。[💥 srvx](https://srvx.h3.dev) 提供通用的服务器层；需要时，可以通过 `event.req.runtime` 获取特定运行时的信息。

## 🌳 类 URLPattern 的路由

路由使用 [🌳 rou3](https://github.com/h3js/rou3) v1，支持类似 [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) 的语法，包括命名参数、正则约束、可选和重复参数、分组及通配符。

```js
app.get("/users/:id(\\d+)", (event) => event.context.params.id);
app.get("/blog/:id(\\d+){-:title}?", (event) => event.context.params);
app.get("/files/:path+", (event) => event.context.params.path);
```

rou3 仍通过树结构逐段匹配路由，因此查找速度很快。它与 URLPattern 有几处有意的差异，例如忽略一个尾部斜杠。完整语法和差异请参阅 [rou3 路由模式文档](https://github.com/h3js/rou3#route-patterns)。

:read-more{to="/guide/basics/routing" title="路由"}

## 🧩 中间件和插件

H3 v2 支持 `(event, next)` 中间件、内置工具（`onRequest`、`onResponse`、`onError`、`basicAuth`、`bodyLimit` 等），以及通过 `definePlugin()` 定义的可复用[插件](/guide/advanced/plugins)。

```js
app.use(async (event, next) => {
  const body = await next();
  event.res.headers.append("x-middleware", "works");
  return body;
});
```

:read-more{to="/guide/basics/middleware" title="中间件"}

## 🔒 类型安全

处理程序、响应和[错误](/guide/basics/error)（`HTTPError`）均有类型定义。已验证的处理程序以及 body、query、params 校验可与任何 [Standard Schema](https://standardschema.dev) 库配合使用。

## 📏 路由规则

全新的 `h3/rules` 引擎可通过一个配置对象，为一组路由添加请求头、重定向、CORS、缓存和代理规则。

```js
import { routeRules } from "h3/rules";

app.use(
  routeRules({
    "/old/**": { redirect: "/new/**" },
    "/assets/**": { headers: { "cache-control": "s-maxage=31536000" } },
    "/api/**": { cors: true },
  }),
);
```

:read-more{to="/guide/rules" title="路由规则"}

## 🧰 内置工具

H3 内置了 Cookie（包括分块 Cookie）、会话、CORS、代理、静态文件、缓存头、服务器发送事件、通过 [🔌 crossws](https://crossws.h3.dev) 实现的 WebSocket、JSON-RPC/MCP 工具，以及 `h3/tracing` 插件。

:read-more{to="/utils" title="工具"}

## ⬆️ 升级

大多数 v1 工具仍可继续使用，已弃用的 v1 名称也仍会导出，以便更轻松地升级。在 Node.js 上运行时，H3 v2 要求 Node.js `>= 20.19`。

:read-more{to="/migration" title="迁移指南"}

## ❤️ 特别感谢

感谢所有[贡献者](https://github.com/h3js/h3/graphs/contributors)、测试 beta 版和候选发布版并反馈问题的每一位用户、[社区成员](https://discord.h3.dev)、在开发期间持续使用 v2 的 [Nitro](https://nitro.build) 社区，以及让开源工作得以持续的[赞助者](/#sponsors)。

::callout{to="https://discord.h3.dev"}
欢迎加入我们的 [Discord](https://discord.h3.dev)，分享你的使用体验和反馈！
::