进阶
会话工具
clearSession(event, config)
清除当前请求的会话数据。
getSession(event, config)
获取当前请求的会话。
sealSession(event, config)
加密并签名当前请求的会话数据。
unsealSession(_event, config, sealed)
解密并验证当前请求的会话数据。
updateSession(event, config, update?)
更新当前请求的会话数据。
useSession(event, config)
为当前请求创建一个会话管理器。
Cookie 工具
deleteCookie(event, name, serializeOptions?)
通过名称删除 Cookie。
getCookie(event, name)
通过名称获取 Cookie 值。
parseCookies(event)
解析请求以获取 HTTP Cookie 头字符串，并返回所有 Cookie 名称-值对的对象。
setCookie(event, name, value, options?)
通过名称设置 Cookie 值。
指纹工具
getRequestFingerprint(event, opts)
获取传入请求的唯一指纹。
WebSocket 工具
defineWebSocket(hooks)
定义 WebSocket 钩子。
defineWebSocketHandler(hooks)
定义 WebSocket 事件处理器。
安全过滤
sanitizeStatusCode(statusCode?, defaultStatusCode)
确保状态码是有效的 HTTP 状态码。
sanitizeStatusMessage(statusMessage)
确保状态消息在响应中安全可用。
允许的字符：横向制表符、空格或可见 ASCII 字符：https://www.rfc-editor.org/rfc/rfc7230#section-3.1.2
基础
withBase(base, input)
返回一个新的事件处理器，在调用原始处理器前移除事件的基础 URL。
示例：
const api = new H3()
.get("/", () => "Hello API!");
const app = new H3();
.use("/api/**", withBase("/api", api.handler));
缓存
handleCacheHeaders(event, opts)
检查请求的缓存头（If-Modified-Since）并添加缓存头（Last-Modified，Cache-Control）。注意：默认会添加 public 缓存控制。
代理
fetchWithEvent(event, req, init?, options?: { fetch: F })
使用事件的上下文和头信息发起 fetch 请求。
getProxyRequestHeaders(event)
获取请求头对象，移除在代理时已知会引起问题的头。
proxy(event, target, opts)
发起代理请求到目标 URL，并将响应返回给客户端。
proxyRequest(event, target, opts)
将传入请求代理到目标 URL。
跨域资源共享（CORS）
appendCorsHeaders(event, options)
向响应追加 CORS 头。
appendCorsPreflightHeaders(event, options)
向响应追加 CORS 预检请求头。
handleCors(event, options)
处理传入请求的 CORS。
如果传入请求是 CORS 预检请求，将追加 CORS 预检头并发送 204 响应。
如果返回值为 true，表示请求已处理，无需进一步操作。
示例：
const app = new H3();
const router = createRouter();
router.use("/", async (event) => {
const corsRes = handleCors(event, {
origin: "*",
preflight: {
statusCode: 204,
},
methods: "*",
});
if (corsRes) {
return corsRes;
}
// 你的代码
});
isCorsOriginAllowed(origin, options)
检查传入请求是否是允许的 CORS 源。
isPreflightRequest(event)
检查传入请求是否是 CORS 预检请求。
服务器发送事件（SSE）
createEventStream(event, opts?)
初始化 EventStream 实例以创建服务器发送事件
示例：
import { createEventStream, sendEventStream } from "h3";
app.get("/sse", (event) => {
const eventStream = createEventStream(event);
// 每秒发送一条消息
const interval = setInterval(async () => {
await eventStream.push("Hello world");
}, 1000);
// 连接终止时清理定时器并关闭流
eventStream.onClosed(async () => {
console.log("closing SSE...");
clearInterval(interval);
await eventStream.close();
});
return eventStream.send();
});
认证
basicAuth(opts)
创建一个基础身份验证中间件。
示例：
import { H3, serve, basicAuth } from "h3";
const auth = basicAuth({ password: "test" });
app.get("/", (event) => `Hello ${event.context.basicAuth?.username}!`, [auth]);
serve(app, { port: 3000 });
requireBasicAuth(event, opts)
为当前请求启用基础身份验证。
示例：
import { defineEventHandler, requireBasicAuth } from "h3";
export default defineEventHandler(async (event) => {
await requireBasicAuth(event, { password: "test" });
return `Hello, ${event.context.basicAuth.username}!`;
});