H3初识——入门介绍之serveStatic、cookie

简介

H3 是一个轻量、快速、可组合的服务器框架，适用于现代 JavaScript 运行时。它基于网页标准原语，如 Request、Response、URL 和 Headers。你可以将 H3 集成到任何兼容的运行时，或者将其他支持 web 的处理器挂载到 H3，几乎不会带来额外延迟。

主要特性

• 极简、快速、无依赖
• 支持中间件和自定义路由
• 兼容 Node.js HTTP 服务

安装

npm  i h3@beta

快速开始

下面是一个使用 H3 创建简单 HTTP 服务的示例：

import { H3, serve } from "h3";

const app = new H3();

app.get("/", (context) => {
  return "Hello H3!";
});

serve(app, { port: 3000 });

静态资源

app.use("/public/**", (event) => {
  return serveStatic(event, {
    getContents: async (id) => {
      // id 是请求的路径，如 /public/xxx.png
      const filePath = join(process.cwd(), id);
      return await readFile(filePath);
    },
    getMeta: async (id) => {
      const filePath = join(process.cwd(), id);
      const fileStat = await stat(filePath);
      return {
        mtime: fileStat.mtime,
        size: fileStat.size,
        type: extname(filePath).slice(1), // 文件扩展名
      };
    },
  });
});

Cookies

设置 cookie

app.get("/set-cookie", (event) => {
  setCookie(event, "token", "123456", {
    httpOnly: true,
    maxAge: 60 * 60 * 24, // 1天
    path: "/",
  });
  event.res.headers.set("Content-Type", "text/plain; charset=utf-8");
  return "已设置 cookie";
});

获取 cookie

app.get("/get-cookie", (event) => {
  event.res.headers.set("Content-Type", "text/plain; charset=utf-8");
  const token = getCookie(event, "token");
  return token || "未找到 token";
});

删除 cookie

app.get("/delete-cookie", (event) => {
  event.res.headers.set("Content-Type", "text/plain; charset=utf-8");
  deleteCookie(event, "token", { path: "/" });
  return "已删除 cookie";
});

参考链接

• H3 官方中文文档

H3 相比 Koa、Express 优势

1. 极致轻量、无依赖

• H3 本身几乎没有依赖，核心包体积极小，启动速度快，适合现代云原生和 Serverless 场景。
• Koa 和 Express 都有一定的依赖体积，Express 依赖更多第三方包。

1. 基于 Web 标准原语

• H3 直接使用 Web 标准的 Request、Response、URL、Headers 等对象，天然兼容多种 JavaScript 运行时（如 Node.js、Deno、Bun、云函数等）。
• Koa、Express 采用自定义的 req/res 封装，迁移到其他运行时时需要适配。

1. 更高性能

• H3 设计极简，内部无多余抽象，性能表现优异，延迟极低。
• Express 由于历史包袱和中间件机制，性能相对较低；Koa 性能较好，但仍有一定抽象损耗。

1. 中间件和路由机制更灵活

• H3 支持函数式中间件和组合，易于扩展和自定义，且中间件链路极简。
• Koa 也有中间件机制，但 Express 的中间件和路由耦合较重。

1. 无状态、易于集成

• H3 适合无状态服务，天然适配 Serverless、边缘计算等现代部署方式。
• Express、Koa 更偏向传统长连接、状态服务。

1. 更好的 TypeScript 支持

• H3 从设计之初就支持 TypeScript，类型推导完善，开发体验更好。
• Express、Koa 的类型支持主要依赖社区维护的类型声明文件。

1. 易于与 Nuxt、Nitro 等现代框架集成

• H3 是 Nuxt 3、Nitro 等现代全栈框架的底层 HTTP 引擎，生态集成度高。
• Express、Koa 主要用于传统 Node.js 服务端开发。