更多工具

基础

withBase(base, input)

Returns a new event handler that strips the event’s base URL before invoking the original handler.

示例：

const api = new H3()
 .get("/", () => "Hello API!");
const app = new H3();
 .use("/api/**", withBase("/api", api.handler));

事件

getEventContext(event)

获取事件的上下文，如果不存在，则在 req.context 上初始化一个新上下文。

isEvent(input)

检查输入是否为 H3Event 对象。

isHTTPEvent(input)

检查输入是否为具有 { req: Request } 签名的对象。

mockEvent(_request, options?)

中间件

bodyLimit(limit)

定义一个中间件，用于检查请求体的大小是否在指定限制内。

如果请求体大小超过限制，则抛出 413 请求实体过大错误。如果你需要自定义该情况的处理，请使用 assertBodySize。

onError(hook)

定义一个错误发生时运行的中间件。

你可以从处理器返回一个新的响应来优雅地处理错误。

onRequest(hook)

定义一个在每次请求时运行的中间件。

onResponse(hook)

定义一个在响应生成后运行的中间件。

你可以从处理器返回一个新的响应以替换原始响应。

WebSocket

defineWebSocket(hooks)

定义 WebSocket 钩子。

示例：

const hooks = defineWebSocket({
  open: (peer) => peer.send("欢迎！"),
  message: (peer, message) => peer.send(message.text()),
  close: (peer) => console.log("已关闭", peer),
});

defineWebSocketHandler(http?)

定义 WebSocket 事件处理器。

默认情况下，非升级（普通 HTTP）请求会收到 426 Upgrade Required 响应。传入一个 http 处理器来改为处理这些请求，从而允许同一路由同时处理 WebSocket 升级和常规 HTTP 请求。WebSocket 升级请求始终会进入 hooks。

注意：http 处理器只处理非升级请求。若要拒绝或自定义升级握手本身，请改用 crossws 的 upgrade 钩子。

示例：

// 仅 WebSocket 路由（非升级请求会收到 `426 Upgrade Required`）
app.get(
  "/_ws",
  defineWebSocketHandler({
    message: (peer, message) => peer.send(message.text()),
  }),
);

示例：

// 在同一路由上同时处理 WebSocket 升级和普通 HTTP
app.get(
  "/_ws",
  defineWebSocketHandler(
    { message: (peer, message) => peer.send(message.text()) },
    () => "发送 WebSocket 升级请求以连接。",
  ),
);

适配器

defineNodeHandler(handler)

defineNodeMiddleware(handler)

fromNodeHandler(handler)

fromWebHandler(handler)

toNodeHandler(app)

将 H3 应用实例转换为具有 (IncomingMessage, ServerResponse) => void 签名的 NodeHandler。