Nitro

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

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

addServerHandler

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

Usage

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

Type

function addServerHandler (handler: NitroEventHandler): void

Parameters

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

PropertyTypeRequiredDescription
handlerstringtrue事件处理器的路径。
routestringfalse路径前缀或路由。如果使用空字符串，则会作为中间件使用。
middlewarebooleanfalse指定这是一个中间件处理程序。中间件会在每个路由上被调用，通常应当不返回内容以便将控制权传递给下一个处理程序。
lazybooleanfalse使用懒加载导入处理程序。当您只想在需要时加载处理程序时很有用。
methodstringfalse路由方法匹配器。如果处理程序名称包含方法名称，则该值将作为默认值使用。

Examples

Basic Usage

您可以使用 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 服务器处理程序。此处理程序将在生产构建中被排除。

Usage

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

Type

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

Parameters

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

PropertyTypeRequiredDescription
handlerEventHandlertrue事件处理器。
routestringfalse路径前缀或路由。如果使用空字符串，则会作为中间件使用。

Examples

Basic Usage

在某些情况下，您可能希望专门为开发目的创建服务器处理程序，例如 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 实例配置的更改不会被应用。

Usage

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

Type

function useNitro (): Nitro

addServerPlugin

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

您可以在 Nitro 文档 中阅读有关 Nitro 插件的更多内容。
在您的插件文件中，必须显式导入 defineNitroPlugin 从 nitropack/runtime。同样的要求适用于 useRuntimeConfig 等工具。

Usage

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

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

Type

function addServerPlugin (plugin: string): void

Parameters

PropertyTypeRequiredDescription
pluginstringtrue插件路径。该插件必须导出一个默认函数，该函数接受 Nitro 实例作为参数。

Examples

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

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

addPrerenderRoutes

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

Usage

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

Type

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

Parameters

PropertyTypeRequiredDescription
routesstring | string[]true要预渲染的路由或路由数组。

addServerImports

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

Usage

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

Type

function addServerImports (dirs: Import | Import[]): void

Parameters

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

PropertyTypeRequiredDescription
namestringtrue要被检测的导入名称。
fromstringtrue要从中导入的模块说明符。
prioritynumberfalse导入的优先级；如果多个导入具有相同名称，则使用优先级最高的那个。
disabledbooleanfalse如果此导入被禁用。
metaRecord<string, any>false导入的元数据。
typebooleanfalse如果此导入是纯类型导入。
typeFromstringfalse在生成类型声明时使用此值作为 from。
asstringfalse将导入作为此名称。

addServerImportsDir

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

Usage

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

Type

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

Parameters

PropertyTypeRequiredDescription
dirsstring | string[]true要注册以供 Nitro 扫描的目录或目录数组。
opts{ prepend?: boolean }false导入目录的选项。如果 prepend 为 true，则该目录将添加到扫描列表的开头。

Examples

您可以使用 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。

Usage

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

Type

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

Parameters

PropertyTypeRequiredDescription
dirsstring | string[]true要注册以供 Nitro 扫描为服务器目录的目录或目录数组。
opts{ prepend?: boolean }false导入目录的选项。如果 prepend 为 true，则该目录将添加到扫描列表的开头。

Examples

您可以使用 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!
})