Nitro

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

Maschinelle Übersetzung ·0 % geprüft

Nitro 是一个开源 TypeScript 框架，用于构建超快速 Web 服务器。Nuxt 使用 Nitro 作为其服务器引擎。您可以使用 useNitro 访问 Nitro 实例（或者在您的模块也应在没有 Nitro 的情况下运行时使用 tryUseNitro），使用 addServerHandler 添加服务器处理程序，使用 addDevServerHandler 添加仅在开发模式下使用的服务器处理程序，使用 addNitroPlugin 添加插件以扩展 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: ServerHandlerInput): void

参数

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

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

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

了解何时应为每个服务器 API 注册一个路径，以及应针对哪个键编写处理程序。

示例

基础用法

您可以使用 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 { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'

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

类型

function addDevServerHandler (handler: DevServerHandlerInput): void

参数

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

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

示例

基础用法

在某些情况下，您可能希望专门为开发目的创建服务器处理程序，例如 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

tryUseNitro

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

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

用法

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

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('ready', () => {
      const nitro = tryUseNitro()
      if (!nitro) {
        // kein Server: alles überspringen, was nur dort laufen würde
        return
      }
    })
  },
})

类型

function tryUseNitro (): Nitro | undefined

addNitroPlugin

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

在 Nuxt v4.6 之前，此函数名为 addServerPlugin。
您可以在 Nitro 文档 中阅读有关 Nitro 插件的更多内容。
在您的插件文件中，必须显式从 nitropack/runtime 导入 defineNitroPlugin。同样的要求适用于 useRuntimeConfig 等工具。

用法

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

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

类型

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

参数

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

示例

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addNitroPlugin(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 中可用，而无需手动导入它们。

如果您想提供一个同时适用于服务端和客户端上下文、并且可在 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: NuxtImport | NuxtImport[]): 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 添加要扫描的目录。当您希望 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 函数：

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

参数

属性类型必需说明
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 函数。

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