H3 v2 正式版说明

H3 v2 于 2026-10-03 正式发布（稳定版 2.0.8）。官方发布说明把这次大版本概括为：一次基于 Web 标准的完整重写，保留了绝大多数 v1 工具的兼容写法，并且（官方宣称）比 v1 更快、更小。本文按官方博客的结构梳理 v2 的六项主张——注意区分「官方定位」与「技术事实」，营销措辞不翻译成硬性技术承诺。

💡 这一节是「为什么升级」的概览；具体怎么改代码请看 8.1（核心变更）和 8.2（弃用清单）。文末「升级」一节会回指这两节。

最小的 v2 应用长这样：

import { H3, serve } from "h3";

// new H3() 直接拿到实例，链式注册路由
const app = new H3().get("/", () => "Hello H3!");

serve(app, { port: 3000 });

一、Web 标准优先

v2 直接构建在 Request、Response、URL、Headers 这四个 Web 平台基础类型之上。Handler 收到的 event.req 就是一个标准的 Request，响应通过 event.res 设置。返回任意值（字符串、对象、Response、流、Blob ……）H3 都会自动转成 Response。

import { defineHandler } from "h3";

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

  event.res.headers.set("x-powered-by", "h3");         // 通过 event.res 写响应
  return { hello: "web" };                             // 返回值自动转 Response
});

这意味着你之前学的 Web 标准 API 在 H3 里直接通用，不需要记一套 H3 特有的请求/响应方法。

二、随处运行

同一份代码可以跑在 Node.js、Bun、Deno、Cloudflare Workers、Service Workers 乃至浏览器里。通用服务层由 srvx 提供；当你确实需要运行时特有的细节时，可通过 event.req.runtime 访问。

三、类 URLPattern 路由

路由引擎换成 rou3 v1，支持接近 URLPattern 的语法：命名参数、正则约束、可选参数、重复参数、分组和通配符。rou3 仍然是「按段在树里匹配」，所以查找很快；它与 URLPattern 有少量刻意不同（例如忽略一个尾斜杠）。

// 命名参数 + 正则约束
app.get("/users/:id(\\d+)", (event) => event.context.params.id);
// 可选分组：:title 可有可无
app.get("/blog/:id(\\d+){-:title}?", (event) => event.context.params);
// 重复参数：匹配多层路径
app.get("/files/:path+", (event) => event.context.params.path);

四、中间件与插件

v2 支持 (event, next) 形式的中间件，内置了 onRequest、onResponse、onError、basicAuth、bodyLimit 等辅助，以及用 definePlugin() 编写的、可复用的插件（详见 5.1）。

// 包裹式中间件：先执行 next，再在响应上加头
app.use(async (event, next) => {
  const body = await next();
  event.res.headers.append("x-middleware", "works");
  return body;
});

五、类型安全

Handler、响应和错误（HTTPError）都是带类型的；校验型 handler 以及对 body / query / params 的校验，可以与任何 Standard Schema 兼容的库（如 Zod）配合。

六、路由规则

新的 h3/rules 引擎用一个配置对象，给一组路由统一加 header、重定向、CORS、缓存和代理——不必再在每个 handler 里手动写。

import { routeRules } from "h3/rules";

// 用 h3/rules 引擎给一组路由统一加规则：重定向、缓存头、CORS
app.use(
  routeRules({
    "/old/**": { redirect: "/new/**" },
    "/assets/**": { headers: { "cache-control": "s-maxage=31536000" } },
    "/api/**": { cors: true },
  }),
);

七、内置工具

H3 内置了一整套工具：Cookie（含分块 Cookie）、会话、CORS、代理、静态文件、缓存头、Server-Sent Events、通过 crossws 的 WebSocket，以及 JSON-RPC / MCP 辅助函数和 h3/tracing 插件——对应本教程第 6 章逐个展开的那些函数。

八、升级

大多数 v1 工具继续可用，被弃用的 v1 名称仍然导出，让升级更平滑。v2 在 Node.js 上运行时要求 Node.js >= 20.19。

具体改动点集中在两处：

• 核心变化（怎么改）：见 8.1 H3 v1 到 v2 迁移：核心变更——send* 改 return/throw、createApp/createRouter 合并为 new H3()、中间件子路径匹配规则变化等。
• 逐项弃用对照（改成什么）：见 8.2 H3 v1 到 v2 迁移：弃用清单——按请求体、Cookie 与 Headers、工具函数、Node 与 Web 适配、类型导出五组列出的 v1→v2 替换表。

如果想知道 v2 的设计思路从哪来，下一节（8.4）回顾 v1.8——那次发布已经把 Web 标准兼容、流式响应、对象式 handler 等基因埋了进去。