Nitro

Nuxt Kit 提供了一系列工具，帮助你使用 Nitro。这些函数允许你添加服务器处理器、插件和预渲染路由。

Nitro 是一个用于构建超快 Web 服务器的开源 TypeScript 框架。Nuxt 使用 Nitro 作为其服务器引擎。你可以使用 useNitro 访问 Nitro 实例，addServerHandler 添加服务器处理器，addDevServerHandler 添加仅在开发模式下使用的服务器处理器，addServerPlugin 添加插件以扩展 Nitro 的运行时行为，以及 addPrerenderRoutes 添加将由 Nitro 预渲染的路由。

`addServerHandler`

添加一个 Nitro 服务器处理器。如果你想创建服务器中间件或自定义路由，可以使用它。

用法

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'),
    })
  },
})

类型

function addServerHandler (handler: NitroEventHandler): void

参数

handler：一个包含以下属性的处理器对象：

属性	类型	必填	描述
`handler`	`string`	`true`	事件处理器的路径。
`route`	`string`	`false`	路径前缀或路由。如果使用空字符串，将被作为中间件使用。
`middleware`	`boolean`	`false`	指定这是一个中间件处理器。中间件会在每个路由上被调用，通常应不返回任何内容以传递给下一个处理器。
`lazy`	`boolean`	`false`	使用惰性加载来导入处理器。当你只想按需加载处理器时这很有用。
`method`	`string`	`false`	路由方法匹配器。如果处理器名称包含方法名，它会被用作默认值。

示例

基础用法

你可以使用 addServerHandler 从你的模块添加一个服务器处理器。

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'),
    })
  },
})

runtime/robots.get.ts

import { defineEventHandler } from 'nitro/h3'

export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`,
  }
})

当你访问 /robots.txt 时，它会返回如下响应：

User-agent: *
Disallow: /

`addDevServerHandler`

添加一个仅在开发模式下使用的 Nitro 服务器处理器。该处理器不会被包含在生产构建中。

用法

import { defineEventHandler } from 'nitro/h3'
import { addDevServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

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

类型

// @errors: 2391
import type { NitroDevEventHandler } from 'nitro/types'
// ---cut---
function addDevServerHandler (handler: NitroDevEventHandler): void

参数

handler：一个包含以下属性的处理器对象：

属性	类型	必填	描述
`handler`	`EventHandler`	`true`	事件处理器。
`route`	`string`	`false`	路径前缀或路由。如果使用空字符串，将被作为中间件使用。

示例

基础用法

在某些情况下，你可能想专门为了开发目的创建一个服务器处理器，例如 Tailwind 配置查看器。

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 没有正确的类型
    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 实例。

你只能在 ready 钩子之后调用 useNitro()。 :

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

用法

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 实例做一些处理
    })
  },
})

类型

function useNitro (): Nitro

`addServerPlugin`

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

你可以在 Nitro 文档中阅读更多关于 Nitro 插件的内容。 :

有必要在你的插件文件中显式地从 `` 导入 definePlugin。同样的 requirement 也适用于诸如 useRuntimeConfig 之类的实用工具。 :

用法

import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

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

类型

function addServerPlugin (plugin: string): void

参数

属性	类型	必填	描述
`plugin`	`string`	`true`	插件的路径。该插件必须导出一个默认函数，该函数接收 Nitro 实例作为参数。

示例

module.ts

import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

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

runtime/plugin.ts

import { definePlugin } from 'nitro'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('on request', event.req.url)
  })

  nitroApp.hooks.hook('response', async (res) => {
    console.log('on response', await res.text())
  })
})

`addPrerenderRoutes`

添加将由 Nitro 预渲染的路由。

用法

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)
    }
  },
})

类型

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

参数

属性	类型	必填	描述
`routes`	`string \| string[]`	`true`	要预渲染的一个路由或一组路由。

`addServerImports`

向服务器添加导入。它让你的导入在 Nitro 中可用，而无需手动导入它们。

如果你想提供一个在服务器和客户端上下文中都能工作、并且可用于 shared/ 目录的工具函数，那么这个函数必须从同一个源文件导入 addImports 和 addServerImports，并且应具有相同的签名。该源文件不应导入任何上下文特定的内容（即 Nitro 上下文、Nuxt 应用上下文），否则可能会在类型检查时引发错误。 :

用法

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' }),
    )
  },
})

类型

function addServerImports (dirs: Import | Import[]): 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 扫描以进行自动导入的目录。

用法

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'))
  },
})

类型

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

参数

属性	类型	必填	描述
`dirs`	`string \| string[]`	`true`	一个或多个要注册供 Nitro 扫描的目录。
`opts`	`{ prepend?: boolean }`	`false`	导入目录的选项。如果 `prepend` 为 `true`，该目录会被添加到扫描列表的开头。

示例

你可以使用 addServerImportsDir 添加一个将由 Nitro 扫描的目录。当你想让 Nitro 从自定义服务器目录自动导入函数时，这很有用。

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'))
  },
})

runtime/server/composables/index.ts

export function useApiSecret () {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}

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

runtime/server/api/hello.ts

import { defineEventHandler } from 'nitro/h3'

const useApiSecret = (): string => ''
// ---cut---
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // 对该 apiSecret 做一些处理
})

`addServerScanDir`

添加将由 Nitro 扫描的目录。它会检查子目录，这些子目录会被像 ~~/server 文件夹一样被注册。

只有 ~~/server/api、~~/server/routes、~~/server/middleware 和 ~~/server/utils 会被扫描。 :

用法

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'))
  },
})

类型

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

参数

属性	类型	必填	描述
`dirs`	`string \| string[]`	`true`	一个或多个要注册供 Nitro 作为服务器目录扫描的目录。
`opts`	`{ prepend?: boolean }`	`false`	导入目录的选项。如果 `prepend` 为 `true`，该目录会被添加到扫描列表的开头。

示例

你可以使用 addServerScanDir 添加一个将由 Nitro 扫描的目录。当你想添加一个自定义服务器目录时这很有用。

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'))
  },
})

runtime/server/utils/index.ts

export function hello () {
  return 'Hello from server utils!'
}

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

runtime/server/api/hello.ts

import { defineEventHandler } from 'nitro/h3'

function hello () {
  return 'Hello from server utils!'
}
// ---cut---
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})