# 服务器工具

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

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

## 快速参考

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

## `nitro`

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

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

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

```ts [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 应用（路由规则、中间件、插件），而不会接触网络：

```ts [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`：

```ts
import { fetch } from "nitro";

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

### 错误处理器

将 [`errorHandler` 配置](/config#errorhandler)指向一个导出自定义错误处理器的文件：

```ts [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" },
  });
});
```

### 运行时插件

插件会在服务器启动时运行一次，并且可以接入[运行时生命周期](/docs/lifecycle)：

```ts [server/plugins/log.ts]
import { definePlugin } from "nitro";

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

更多信息请参阅[插件指南](/docs/plugins)。

## `nitro/h3`

重新导出所有 [H3 v2](https://h3.dev) 工具：`readBody`、`getQuery`、`getCookie`、`setCookie`、`proxy`、`redirect` 等。

```ts [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 工具文档](https://h3.dev/utils)。
::

## `nitro/cache`

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

```ts
import { defineCachedHandler } from "nitro/cache";

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

有关选项、缓存键和失效处理，请参阅[缓存指南](/docs/cache)。

## `nitro/storage`

| 导出项 | 描述 |
| --- | --- |
| `useStorage` | 访问键值[存储层](/docs/storage)，也可以指定基础路径（例如 `useStorage("data")`{lang=ts}） |

```ts
import { useStorage } from "nitro/storage";

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

有关挂载点和驱动程序，请参阅 [KV 存储指南](/docs/storage)。

## `nitro/database`

| 导出项 | 描述 |
| --- | --- |
| `useDatabase` | 访问已配置的 SQL [数据库](/docs/database)连接（默认：`useDatabase()`{lang=ts}，命名数据库：`useDatabase("users")`{lang=ts}） |

```ts
import { useDatabase } from "nitro/database";

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

有关连接器和配置，请参阅[数据库指南](/docs/database)。

## `nitro/runtime-config`

| 导出项 | 描述 |
| --- | --- |
| `useRuntimeConfig` | 访问[运行时配置](/docs/configuration#runtime-configuration)，可使用 `NITRO_*` 环境变量覆盖 |

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

const { apiToken } = useRuntimeConfig();
```

## `nitro/task`

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

```ts
import { runTask } from "nitro/task";

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

请参阅[任务指南](/docs/tasks)。任务处于实验阶段，需要启用 `experimental.tasks` 标志。

## `nitro/app`

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

| 导出项 | 描述 |
| --- | --- |
| `useNitroApp` | 访问当前的 [Nitro 应用实例](/docs/lifecycle)（`fetch`、`hooks` 等） |
| `useNitroHooks` | 访问[运行时钩子](/docs/plugins#nitro-runtime-hooks)实例，以便在插件外注册钩子 |
| `getRouteRules` | 获取方法和路径名对应的已解析[路由规则](/docs/routing#route-rules)：`getRouteRules("GET", "/blog/post")`{lang=ts} |
| `serverFetch`、`fetch` | 与[主入口导出项](#internal-fetch)相同 |

```ts
import { useNitroHooks } from "nitro/app";

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

## `nitro/context`

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

```ts
import { useRequest } from "nitro/context";

const request = useRequest();
```

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

## `nitro/config`

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

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

## `nitro/types`

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

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

## `nitro/vite`

| 导出项 | 描述 |
| --- | --- |
| `nitro` | Nitro [Vite 插件](/docs/vite) |

```ts [vite.config.ts]
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

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

同时也会导出 `NitroPluginConfig` 和 `ServiceConfig` 类型。请参阅 [Vite 集成指南](/docs/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? })`） |

```ts
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`）属于内部入口，在应用代码中很少需要使用。