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()
      // Do something with Nitro instance
    })
  },
})

类型

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导入的元数据。
类型booleanfalse如果此导入是纯类型导入。
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 函数

runtime/server/api/hello.ts
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // Do something with the 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!
})