Nitro

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

Nitro 是一个开源的 TypeScript 框架，用于构建超快速的 web 服务器。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: 一个处理器对象，包含以下属性：

属性类型是否必须说明
handlerstringtrue事件处理器的路径。
routestringfalse路径前缀或路由。如果使用空字符串，则作为中间件使用。
middlewarebooleanfalse指定该处理器是中间件。中间件会在所有路由上调用，通常应返回空以传递给下一个处理器。
lazybooleanfalse使用延迟加载导入处理器。当你只想按需加载处理器时，这个很有用。
methodstringfalse路由方法匹配器。如果处理器名称包含方法名，会被用作默认值。

示例

基本用法

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

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

访问 /robots.txt 时，将返回如下响应：

User-agent: *
Disallow: /

addDevServerHandler

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

用法

import { defineEventHandler } from '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',
    })
  },
})

类型

function addDevServerHandler (handler: NitroDevEventHandler): void

参数

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

属性类型是否必须说明
handlerEventHandlertrue事件处理器。
routestringfalse路径前缀或路由。如果使用空字符串，则作为中间件使用。

示例

基本用法

有时，你可能想创建一个仅供开发使用的服务器处理器，例如 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 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 实例。

你只能在 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 插件的内容。
你需要在插件文件中显式从 nitropack/runtime 导入 defineNitroPlugin。同样地，诸如 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

参数

属性类型是否必须说明
pluginstringtrue插件路径。插件必须默认导出一个函数，该函数接受 Nitro 实例作为参数。

示例

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

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

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

参数

属性类型是否必须说明
routesstring | string[]true需预渲染的路由或路由数组。

addServerImports

向服务器添加导入。这样你的导入在 Nitro 中可用，无需手动导入。

用法

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: 一个对象或对象数组，包含以下属性：

属性类型是否必须说明
namestringtrue要检测的导入名称。
fromstringtrue导入的模块标识符。
prioritynumberfalse导入优先级；如果多个导入具有相同名称，将使用优先级最高的那个。
disabledbooleanfalse是否禁用此导入。
metaRecord<string, any>false导入的元数据。
typebooleanfalse是否为纯类型导入。
typeFromstringfalse生成类型声明时使用的 from 值。
asstringfalse以该名称导入。

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

参数

属性类型是否必须说明
dirsstring | string[]true一个目录或目录数组，注册后由 Nitro 扫描以自动导入。
opts{ prepend?: boolean }false导入目录的选项。如果 prepend 为 true，则将目录添加到扫描列表的前面。

示例

你可以使用 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'))
  },
})

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

runtime/server/api/hello.ts
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

参数

属性类型是否必须说明
dirsstring | string[]true一个目录或目录数组，注册后由 Nitro 扫描为服务器目录。
opts{ prepend?: boolean }false导入目录的选项。如果 prepend 为 true，则将目录添加到扫描列表的前面。

示例

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

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

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

runtime/server/api/hello.ts
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})