安全

认证

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 { defineHandler, requireBasicAuth } from "h3";
export default defineHandler(async (event) => {
  await requireBasicAuth(event, { password: "test" });
  return `Hello, ${event.context.basicAuth.username}!`;
});

会话

clearSession(event, config)

清除当前请求的会话数据。

getSession(event, config)

获取当前请求的会话。

sealSession(event, config)

加密并签名当前请求的会话数据。

unsealSession(_event, config, sealed)

解密并验证当前请求的会话数据。

updateSession(event, config, update?)

更新当前请求的会话数据。

useSession(event, config)

为当前请求创建一个会话管理器。

指纹

getRequestFingerprint(event, opts)

获取传入请求的唯一指纹。

跨域资源共享（CORS）

appendCorsHeaders(event, options)

向响应中添加 CORS 头。

appendCorsPreflightHeaders(event, options)

向响应中添加 CORS 预检请求头。

handleCors(event, options)

处理传入请求的 CORS。

如果传入请求是 CORS 预检请求，将添加 CORS 预检请求头并发送 204 响应。

如果返回值不是 false，表示请求已被处理，无需进一步操作。

示例：

const app = new H3();
app.all("/", async (event) => {
  const corsRes = handleCors(event, {
    origin: "*",
    preflight: {
      statusCode: 204,
    },
    methods: "*",
  });
  if (corsRes !== false) {
    return corsRes;
  }
  // 你的代码在此
});

isCorsOriginAllowed(origin, options)

检查来源是否被允许。

isPreflightRequest(event)

检查传入请求是否为 CORS 预检请求。

路径

resolveDotSegments(path, opts?)

解析路径中的 . 和 .. 段，并且绝不会超出根目录 /。结果始终是一个带单个前导 / 的绝对路径，因此它不可能是协议相对形式（//host）。

同时还会在任意 %25 嵌套深度下解码百分号编码的点段（%2e、%252e、...），并将 \ 规范化为 /，因此编码形式或基于反斜杠的路径穿越（例如 %2e%2e/、..\..\）会与字面量 ../ 一样被捕获。

默认情况下，%2f/%5c（编码的路径分隔符）会保持不变——参见 {@link ResolveDotSegmentsOptions.decodeSlashes}。

只有 ./.. 的解析以及上述解码会更改字符串；其他所有百分号编码（%20、非 ASCII、%3A，以及任何未构成完整段的 %2e）都会保持原样，因此结果会与未解码的 event.url.pathname 处于相同表示形式，并且能与路由/规则一致地匹配。内部空段会被保留（/a//b 仍然是 /a//b，符合 WHATWG URL 规范化）——只保证前导斜杠是单个，因此如果使用方进行精确前缀匹配，应以同样方式规范化其允许列表。