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 hook 之后调用 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 文档.
有必要在您的插件文件中从 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 中可用，而无需手动导入它们。

如果你想提供一个在服务器和客户端上下文都有效并在 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: 具有以下属性的对象或对象数组

属性类型必需描述
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!
})