服务器工具

可在服务器代码中从 nitro 及其子路径导入的所有内容的参考

Nitro 没有自动导入：每个工具都必须从主 nitro 入口或其子路径之一显式导入。本页面列出了每个导出项对应的导入路径。

#快速参考

你想要执行的操作	导入
定义事件处理器	`import { defineHandler } from "nitro"`
定义中间件	`import { defineMiddleware } from "nitro"`
抛出 HTTP 错误	`import { HTTPError } from "nitro"`
读取请求体、查询参数、Cookie 等	`import { readBody, getQuery } from "nitro/h3"`
在内部调用自己的路由	`import { serverFetch } from "nitro"`
处理 WebSocket 连接	`import { defineWebSocketHandler } from "nitro"`
添加运行时插件	`import { definePlugin } from "nitro"`
自定义错误响应	`import { defineErrorHandler } from "nitro"`
缓存处理器或函数	`import { defineCachedHandler, defineCachedFunction } from "nitro/cache"`
读写键值存储	`import { useStorage } from "nitro/storage"`
查询 SQL 数据库	`import { useDatabase } from "nitro/database"`
访问运行时配置	`import { useRuntimeConfig } from "nitro/runtime-config"`
定义并运行任务	`import { defineTask, runTask } from "nitro/task"`
访问应用实例和钩子	`import { useNitroApp, useNitroHooks } from "nitro/app"`
配置 Nitro（`nitro.config.ts`）	`import { defineConfig } from "nitro"`
将 Nitro 用作 Vite 插件	`import { nitro } from "nitro/vite"`

#`nitro`

主入口包含日常路由处理器所需的一切内容。

导出项	描述
`defineHandler`	为路由或中间件文件定义事件处理器
`defineMiddleware`	定义一个在路由处理器之前运行的中间件
`defineWebSocketHandler`	为路由文件定义一个 WebSocket 处理器
`definePlugin`	定义一个在服务器启动时运行的运行时插件
`defineErrorHandler`	定义自定义错误处理器，替代内置错误页面
`defineConfig`	定义 Nitro 配置（用于 `nitro.config.ts`，不用于运行时代码）
`defineRouteMeta`	附加路由元数据，例如 OpenAPI 规范（构建时宏）
`HTTPError`	使用状态码抛出 HTTP 错误：`throw new HTTPError("Not found", { status: 404 })`
`HTTPResponse`	从处理器返回带有自定义状态码和标头的响应体
`html`	返回 HTML 响应（`text/html` 内容类型）的带标签模板字面量
`serverFetch`	在内部调用自己的路由，无需经过网络往返
`fetch`	类似全局 `fetch`，但以 `/` 开头的路径会路由到自己的服务器

常用类型也会导出：H3Event、EventHandlerRequest 和 EventHandlerWithFetch。

server/routes/hello.ts

import { defineHandler, HTTPError } from "nitro";

export default defineHandler((event) => {
  const name = event.url.searchParams.get("name");
  if (!name) {
    throw new HTTPError("Missing name", { status: 400 });
  }
  return { hello: name };
});

#内部 fetch

serverFetch 直接调用自己应用中的路由：请求会经过 Nitro 应用（路由规则、中间件、插件），而不会接触网络：

server/routes/summary.ts

import { defineHandler, serverFetch } from "nitro";

export default defineHandler(async () => {
  const res = await serverFetch("/api/stats"); // returns a web Response
  return { stats: await res.json() };
});

fetch 导出项是一个通用变体：绝对路径（以 / 开头）会通过 serverFetch 在内部处理，其他路径则回退到全局 fetch：

import { fetch } from "nitro";

await fetch("/api/hello"); // handled by your own server
await fetch("https://example.com"); // regular network fetch

#错误处理器

将 errorHandler 配置指向一个导出自定义错误处理器的文件：

error.ts

import { defineErrorHandler } from "nitro";

export default defineErrorHandler((error, event) => {
  return new Response(`[custom error] ${error.message}`, {
    status: error.status,
    headers: { "Content-Type": "text/plain" },
  });
});

#运行时插件

插件会在服务器启动时运行一次，并且可以接入运行时生命周期：

server/plugins/log.ts

import { definePlugin } from "nitro";

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook("request", (event) => {
    console.log("request:", event.url.pathname);
  });
});

更多信息请参阅插件指南。

#`nitro/h3`

重新导出所有 H3 v2 工具：readBody、getQuery、getCookie、setCookie、proxy、redirect 等。

server/routes/form.post.ts

import { defineHandler } from "nitro";
import { readBody, getCookie } from "nitro/h3";

export default defineHandler(async (event) => {
  const body = await readBody(event);
  const session = getCookie(event, "session");
  return { body, session };
});

Note

完整列表请参阅 H3 工具文档。

#`nitro/cache`

导出项	描述
`defineCachedHandler`	为事件处理器包装缓存
`defineCachedFunction`	缓存任意（异步）函数的结果

import { defineCachedHandler } from "nitro/cache";

export default defineCachedHandler(() => `Generated at ${new Date().toISOString()}`, {
  maxAge: 60,
});

有关选项、缓存键和失效处理，请参阅缓存指南。

#`nitro/storage`

导出项	描述
`useStorage`	访问键值存储层，也可以指定基础路径（例如 `useStorage("data")`）

import { useStorage } from "nitro/storage";

await useStorage("data").set("visits", 42);

有关挂载点和驱动程序，请参阅 KV 存储指南。

#`nitro/database`

导出项	描述
`useDatabase`	访问已配置的 SQL 数据库连接（默认：`useDatabase()`，命名数据库：`useDatabase("users")`）

import { useDatabase } from "nitro/database";

const db = useDatabase();
const { rows } = await db.sql`SELECT * FROM users`;

有关连接器和配置，请参阅数据库指南。

#`nitro/runtime-config`

导出项	描述
`useRuntimeConfig`	访问运行时配置，可使用 `NITRO_*` 环境变量覆盖

import { useRuntimeConfig } from "nitro/runtime-config";

const { apiToken } = useRuntimeConfig();

#`nitro/task`

导出项	描述
`defineTask`	在 `server/tasks/` 文件中定义一个任务
`runTask`	在服务器代码的任意位置按名称运行任务

import { runTask } from "nitro/task";

const { result } = await runTask("db:migrate", { payload: { force: true } });

请参阅任务指南。任务处于实验阶段，需要启用 experimental.tasks 标志。

#`nitro/app`

对正在运行的 Nitro 应用进行更底层的访问。

导出项	描述
`useNitroApp`	访问当前的 Nitro 应用实例（`fetch`、`hooks` 等）
`useNitroHooks`	访问运行时钩子实例，以便在插件外注册钩子
`getRouteRules`	获取方法和路径名对应的已解析路由规则：`getRouteRules("GET", "/blog/post")`
`serverFetch`、`fetch`	与主入口导出项相同

import { useNitroHooks } from "nitro/app";

useNitroHooks().hook("error", (error) => {
  console.error(error);
});

#`nitro/context`

导出项	描述
`useRequest`	在请求生命周期内的任意位置访问当前请求，无需在各处传递 `event`

import { useRequest } from "nitro/context";

const request = useRequest();

Warning

useRequest 处于实验阶段：它需要 experimental.asyncContext: true 配置标志，并且仅在支持 AsyncLocalStorage 的运行时（Node.js 和兼容运行时）上有效。

#`nitro/config`

导出项	描述
`defineConfig`	与主 `nitro` 入口导出的 `defineConfig` 相同（也别名为 `defineNitroConfig`）

建议直接从 "nitro" 导入 defineConfig。

#`nitro/types`

仅类型入口，包含所有公开的 Nitro 类型，包括 NitroConfig、Nitro、NitroApp、NitroAppPlugin、NitroErrorHandler、NitroRuntimeConfig、NitroRuntimeHooks 和 Task。

import type { NitroRuntimeConfig } from "nitro/types";

#`nitro/vite`

导出项	描述
`nitro`	Nitro Vite 插件

vite.config.ts

import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [nitro()],
});

同时也会导出 NitroPluginConfig 和 ServiceConfig 类型。请参阅 Vite 集成指南。

#`nitro/builder`

面向无需 CLI 即可驱动 Nitro 的工具的编程式 API（构建包装器、框架集成）。

导出项	描述
`createNitro`	根据内联配置（以及 `rootDir` 中的 `nitro.config`）创建 Nitro 实例
`loadOptions`	加载并解析 Nitro 选项，但不创建实例
`prepare`	清理输出目录
`copyPublicAssets`	将公共资源复制到输出目录
`prerender`	预渲染路由
`build`	构建服务器包
`createDevServer`	为 Nitro 实例创建开发服务器
`getBuildInfo`	读取上次构建的 `nitro.json`（接受 `rootDir` 或 `{ rootDir, outputDir }`）
`startPreview`	启动构建的进程内预览（`{ rootDir, outputDir?, loader? }` 返回 `{ fetch, upgrade?, close }`）
`deploy`	为已有构建运行预设的部署命令（`deploy(nitro, { args? })`）

import { build, copyPublicAssets, createNitro, deploy, prepare, prerender } from "nitro/builder";

const nitro = await createNitro({ rootDir: ".", dev: false, preset: "cloudflare_module" });
await prepare(nitro);
await copyPublicAssets(nitro);
await prerender(nitro);
await build(nitro);
await deploy(nitro, { args: ["--env", "staging"] });
await nitro.close();

deploy 使用已解析选项中的 commands.deploy。它可以是 shell 命令（从 rootDir 运行，并将 ./ 路径重写为输出目录），也可以是以编程方式执行部署的预设所使用的函数（例如 zephyr）。缺少部署命令的预设会抛出错误。

#其他入口

其余子路径（用于获取包版本和路径的 nitro/meta、nitro/vite/runtime、nitro/tsconfig）属于内部入口，在应用代码中很少需要使用。

Edit this page

Previous Vite 集成 Next TypeScript

On this page

服务器工具

#快速参考

#nitro

#内部 fetch

#错误处理器

#运行时插件

#nitro/h3

#nitro/cache

#nitro/storage

#nitro/database

#nitro/runtime-config

#nitro/task

#nitro/app

#nitro/context

#nitro/config

#nitro/types

#nitro/vite

#nitro/builder