---
title: "Nitro"
description: "Nuxt Kit 提供了一组工具来帮助您使用 Nitro。 这些函数允许您添加服务器处理程序、插件和预渲染路由。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/kit/nitro"
---
# Nitro

> Nuxt Kit 提供了一组工具来帮助您使用 Nitro。 这些函数允许您添加服务器处理程序、插件和预渲染路由。

Nitro 是一个开源 TypeScript 框架，用于构建超快速 Web 服务器。Nuxt 使用 Nitro 作为其服务器引擎。您可以使用 `useNitro` 访问 Nitro 实例（或者在您的模块也应在没有 Nitro 的情况下运行时使用 `tryUseNitro`），使用 `addServerHandler` 添加服务器处理程序，使用 `addDevServerHandler` 添加仅在开发模式下使用的服务器处理程序，使用 `addNitroPlugin` 添加插件以扩展 Nitro 的运行时行为，并使用 `addPrerenderRoutes` 添加由 Nitro 预渲染的路由。

## `addServerHandler`

添加一个 Nitro 服务器处理程序。如果您想创建服务器中间件或自定义路由，请使用此方法。

### 用法

```ts twoslash
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})
```

### 类型

```ts
function addServerHandler (handler: ServerHandlerInput): void
```

### 参数

**handler**：一个具有以下属性的处理程序对象：

| 属性           | 类型                                                              | 必需      | 说明                                                     |
| ------------ | --------------------------------------------------------------- | ------- | ------------------------------------------------------ |
| `handler`    | `string \| { nuxt?: string, nitro2?: string, nitro3?: string }` | `true`  | 事件处理程序的路径，或每个服务器 API 对应的一个路径。Nuxt 会注册应用程序服务器可运行的实现。    |
| `route`      | `string`                                                        | `false` | 要精确匹配的路由。以 `/**` 结尾可同时匹配其下方的路径。如果使用空字符串，则会将处理程序注册为中间件。 |
| `middleware` | `boolean`                                                       | `false` | 指定这是一个中间件处理程序。中间件会在每个路由上调用，通常应不返回任何内容，以便交给下一个处理程序。     |
| `lazy`       | `boolean`                                                       | `false` | 使用惰性加载导入处理程序。当您只想按需加载处理程序时，这会很有用。                      |
| `method`     | `string`                                                        | `false` | 路由器方法匹配器。如果处理程序名称包含方法名称，则会将其用作默认值。                     |

以 `/**` 结尾的路由也会匹配其基础路径，因此 `route: '/_fonts/**'` 会提供 `/_fonts` 及其下方的所有内容。在路由器仅匹配基础路径下方路径的 Nitro 2 主机上，Nuxt 会将基础路径注册为第二个路由，以便一次注册在两者上的行为保持一致。

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/modules/server-compatibility"}
了解何时应为每个服务器 API 注册一个路径，以及应针对哪个键编写处理程序。
::

### 示例

#### 基础用法

您可以使用 `addServerHandler` 从您的模块中添加服务器处理程序。

::code-group
```ts twoslash [module.ts]
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})
```

```ts twoslash [runtime/robots.get.ts]
export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`,
  }
})
```
::

当您访问 `/robots.txt` 时，它将返回以下响应：

```txt
User-agent: *
Disallow: /
```

## `addDevServerHandler`

添加仅在开发模式下使用的 Nitro 服务器处理程序。此处理程序将在生产构建中被排除。

### 用法

```ts twoslash
import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addDevServerHandler({
      handler: {
        nuxt: () => new Response(`Response generated at ${new Date().toISOString()}`),
      },
      route: '/_handler',
    })
  },
})
```

### 类型

```ts
function addDevServerHandler (handler: DevServerHandlerInput): void
```

### 参数

**handler**：一个具有以下属性的处理程序对象：

| 属性           | 类型                                                                                                          | 必需      | 说明                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `handler`    | `EventHandler \| { nuxt?: (event: RequestEvent) => unknown, nitro2?: EventHandler, nitro3?: EventHandler }` | `true`  | 事件处理程序，或按服务器 API 注册处理程序。Nuxt 会注册当前服务器构建器可以运行的实现。                                   |
| `route`      | `string`                                                                                                    | `false` | 要匹配的路由。以 `/**` 结尾可同时匹配其下路径。在 `nitropack` v2 主机上，不带 `/**` 的路由也会匹配其下路径。空字符串表示注册为中间件。 |
| `method`     | `string`                                                                                                    | `false` | 要匹配的 HTTP 方法，例如 `'POST'`。在 `nitropack` v2 主机上，处理程序会对所有方法运行。                        |
| `middleware` | `boolean`                                                                                                   | `false` | 在路由处理程序之前运行。返回空值即可将请求传递给下一个处理程序。在 `nitropack` v2 主机上，所有开发处理程序都会作为中间件运行。            |
| `meta`       | `object`                                                                                                    | `false` | 路由元数据，例如 OpenAPI 操作信息。Nitro v3 会将其附加到非中间件处理程序上。                                    |

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/modules/server-compatibility#dev-server-handlers"}
了解如何为每种服务器 API 编写开发服务器处理程序，以及各实现会匹配哪些路径。
::

### 示例

#### 基础用法

在某些情况下，您可能希望专门为开发目的创建服务器处理程序，例如 Tailwind 配置查看器。

```ts
import { joinURL } from 'ufo'
import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (options, nuxt) {
    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')

    // @ts-expect-error - tailwind-config-viewer does not have correct types
    const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
    const viewerDevMiddleware = createServer({ tailwindConfigProvider: () => options, routerPrefix: route }).asMiddleware()

    addDevServerHandler({ route, handler: viewerDevMiddleware })
  },
})
```

## `useNitro`

返回 Nitro 实例。

::warning
您只能在 `ready` 钩子之后调用 `useNitro()`。
::

::note
对 Nitro 实例配置的更改不会被应用。
::

### 用法

```ts
import { defineNuxtModule, useNitro } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      // 使用 Nitro 实例进行操作
    })
  },
})
```

### 类型

```ts
function useNitro (): Nitro
```

## `tryUseNitro`

返回 Nitro 实例，如果不存在则返回 `undefined`。

在 `ready` 钩子运行之前不存在 Nitro 实例；当配置的 [`server.builder`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#builder-1) 不使用 Nitro 时，也完全不存在 Nitro 实例，例如输出仅客户端 SPA 的构建器。在任何应当能够在没有服务器的情况下继续运行的场景中，请使用此函数而不是 `useNitro()`：在这种情况下，服务器路由、路由规则和预渲染都不存在。

### 用法

```ts
import { defineNuxtModule, tryUseNitro } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('ready', () => {
      const nitro = tryUseNitro()
      if (!nitro) {
        // no server: skip anything that would only run there
        return
      }
    })
  },
})
```

### 类型

```ts
function tryUseNitro (): Nitro | undefined
```

## `addNitroPlugin`

向 Nitro 添加插件以扩展其运行时行为。

::note
在 Nuxt v4.6 之前，此函数名为 `addServerPlugin`。
::

::tip
您可以在 [Nitro 文档](https://nitro.zhcndoc.com/guide/plugins) 中阅读有关 Nitro 插件的更多内容。
::

::warning
在您的插件文件中，必须显式从 `nitropack/runtime` 导入 `defineNitroPlugin`。同样的要求适用于 `useRuntimeConfig` 等工具。
::

### 用法

```ts twoslash
import { addNitroPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addNitroPlugin(resolve('./runtime/plugin.ts'))
  },
})
```

### 类型

```ts
function addNitroPlugin (plugin: string | { nitro2?: string, nitro3?: string }): void
```

### 参数

| 属性       | 类型                                               | 必需     | 说明                                                                           |
| -------- | ------------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| `plugin` | `string \| { nitro2?: string, nitro3?: string }` | `true` | 插件的路径，或为每个 Nitro 主版本提供一个路径，以便模块为每个版本提供相应的实现。插件必须导出一个默认函数，该函数接受 Nitro 实例作为参数。 |

### 示例

::code-group
```ts [module.ts]
import { addNitroPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addNitroPlugin(resolve('./runtime/plugin.ts'))
  },
})
```

```ts [runtime/plugin.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('on request', event.path)
  })

  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
    console.log('on response', event.path, { body })
  })

  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
    console.log('on after response', event.path, { body })
  })
})
```
::

## `addPrerenderRoutes`

向 Nitro 添加要预渲染的路由。

### 用法

```ts
import { addPrerenderRoutes, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-sitemap',
    configKey: 'sitemap',
  },
  defaults: {
    sitemapUrl: '/sitemap.xml',
    prerender: true,
  },
  setup (options) {
    if (options.prerender) {
      addPrerenderRoutes(options.sitemapUrl)
    }
  },
})
```

### 类型

```ts
function addPrerenderRoutes (routes: string | string[]): void
```

### 参数

| 属性       | 类型                   | 必需     | 说明            |
| -------- | -------------------- | ------ | ------------- |
| `routes` | `string \| string[]` | `true` | 要预渲染的路由或路由数组。 |

## `addServerImports`

向服务端添加导入。这样可以使您的导入在 Nitro 中可用，而无需手动导入它们。

::warning
如果您想提供一个同时适用于服务端和客户端上下文、并且可在 [`shared/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/shared) 目录中使用的工具函数，则该函数必须同时从同一个源文件导入，用于 [`addImports`](https://nuxt.zhcndoc.com/docs/4.x/api/kit/autoimports#addimports) 和 `addServerImports`，并且签名必须完全相同。该源文件不应导入任何特定于上下文的内容（例如 Nitro 上下文、Nuxt 应用上下文），否则可能会导致类型检查错误。
::

### 用法

```ts twoslash
import { addServerImports, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const names = [
      'useStoryblok',
      'useStoryblokApi',
      'useStoryblokBridge',
      'renderRichText',
      'RichTextSchema',
    ]

    names.forEach(name =>
      addServerImports({ name, as: name, from: '@storyblok/vue' }),
    )
  },
})
```

### 类型

```ts
function addServerImports (dirs: NuxtImport | NuxtImport[]): void
```

### 参数

`imports`：一个对象或对象数组，具有以下属性：

| 属性         | 类型                    | 必需      | 说明                               |
| ---------- | --------------------- | ------- | -------------------------------- |
| `name`     | `string`              | `true`  | 要检测的导入名称。                        |
| `from`     | `string`              | `true`  | 要从中导入的模块说明符。                     |
| `priority` | `number`              | `false` | 导入的优先级；如果多个导入具有相同名称，则使用优先级最高的那个。 |
| `disabled` | `boolean`             | `false` | 指示是否禁用此导入。                       |
| `meta`     | `Record<string, any>` | `false` | 导入的元数据。                          |
| `type`     | `boolean`             | `false` | 指示此导入是否为纯类型导入。                   |
| `typeFrom` | `string`              | `false` | 生成类型声明时使用此值作为 `from`。            |
| `as`       | `string`              | `false` | 将导入作为此名称。                        |

## `addServerImportsDir`

添加一个目录以供 Nitro 扫描自动导入。

### 用法

```ts twoslash
import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})
```

### 类型

```ts
function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean }): void
```

### 参数

| 属性     | 类型                      | 必需      | 说明                                             |
| ------ | ----------------------- | ------- | ---------------------------------------------- |
| `dirs` | `string \| string[]`    | `true`  | 要注册以供 Nitro 扫描的目录或目录数组。                        |
| `opts` | `{ prepend?: boolean }` | `false` | 导入目录的选项。如果 `prepend` 为 `true`，则该目录将添加到扫描列表的开头。 |

### 示例

您可以使用 `addServerImportsDir` 向 Nitro 添加要扫描的目录。当您希望 Nitro 自动从自定义服务器目录导入函数时，这非常有用。

::code-group
```ts twoslash [module.ts]
import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})
```

```ts twoslash [runtime/server/composables/index.ts]
export function useApiSecret () {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}
```
::

然后您可以在服务器代码中使用 `useApiSecret` 函数：

```ts twoslash [runtime/server/api/hello.ts]
const useApiSecret = (): string => ''
// ---cut---
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // 使用 apiSecret 进行操作
})
```

## `addServerScanDir`

添加要由 Nitro 扫描的目录。它将检查子目录，并像注册 `~/server` 文件夹一样注册它们。

::note
仅扫描 `~/server/api`、`~/server/routes`、`~/server/middleware` 和 `~/server/utils`。
::

### 用法

```ts twoslash
import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

### 类型

```ts
function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean }): void
```

### 参数

| 属性     | 类型                      | 必需      | 说明                                             |
| ------ | ----------------------- | ------- | ---------------------------------------------- |
| `dirs` | `string \| string[]`    | `true`  | 要注册为 Nitro 服务器扫描目录的目录或目录数组。                    |
| `opts` | `{ prepend?: boolean }` | `false` | 导入目录的选项。如果 `prepend` 为 `true`，则该目录将添加到扫描列表的开头。 |

### 示例

您可以使用 `addServerScanDir` 向 Nitro 添加要扫描的目录。当您想添加自定义服务器目录时，这非常有用。

::code-group
```ts twoslash [module.ts]
import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

```ts twoslash [runtime/server/utils/index.ts]
export function hello () {
  return 'Hello from server utils!'
}
```
::

然后您可以在服务器代码中使用 `hello` 函数。

```ts twoslash [runtime/server/api/hello.ts]
function hello () {
  return 'Hello from server utils!'
}
// ---cut---
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})
```

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/nitro.ts)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.