H3 工具函数总览

H3 的定位是「组合式框架」：它不给你一个大而全的核心，而是给你一个极小的 H3 实例，剩下的能力全部是一个个独立函数，用到哪个 import 哪个。这意味着两件事——打包体积由你的 import 决定，以及你需要先知道「哪个函数管哪件事」。

这一节是第 6 章的导航：先讲命名规律，再给分区索引和「我要做什么 → 用哪个」的速查表。后面九节按类别展开。

一条贯穿全部工具的命名规律

看名字就知道函数干什么、会不会抛错、返回什么。这是 H3 工具集最省学习成本的地方：

记这一条的实际收益是：看到 getRouterParams 就知道它不会因为参数缺失抛错，看到 requireContentType 就知道它可能抛 415，写 try/catch 时不用翻文档。

八个分区

「我要做什么」速查表

这张表按意图查，比按字母翻文档快：

工具函数只做三件事

别看函数多，行为模式只有三类。分清楚，调试会快很多。

第一类：直接改 event.res，返回 undefined。

import { H3, setCookie } from "h3";

const app = new H3().get("/", (event) => {
  // setCookie 只往 event.res.headers 追加 Set-Cookie，本身不产生响应
  setCookie(event, "session", "abc", { httpOnly: true, path: "/" });
  return "ok";
});

第二类：返回一个值，交给你 return。

import { H3, redirect, noContent } from "h3";

const app = new H3()
  .get("/old", () => redirect("/new"))
  // noContent 返回的是一个空响应对象，必须 return 出去
  .get("/ping", () => noContent(204));

第三类：可能短路整个请求，靠返回值判断。

import { H3, handleCors } from "h3";

const app = new H3().all("/", (event) => {
  const res = handleCors(event, { origin: "*" });
  // 不是 false 说明已经处理完（比如预检返回了 204），直接返回
  if (res !== false) {
    return res;
  }
  return "ok";
});

第三类最容易写错：以为 handleCors 是「加个头就完事」，其实它在预检请求上会直接把响应做完。这个契约在 6.6 会展开。

💡 官方文档这几页的正文是从源码注释自动生成的，只列了签名和简短说明。本教程在每节里补了「什么时候该用、什么情况会踩坑」，但签名细节以源码为准——尤其是 opts 里的可选项，文档不一定列全。

延伸阅读

• 请求体、查询参数与 QUERY 方法：见 6.2 请求体与查询参数
• 条件缓存与请求信息读取：见 6.3 条件缓存与更多请求工具
• 响应构造、静态资源与清理回调：见 6.4 响应工具