v3.16
GitHub

Nitro

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

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

addServerHandler

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

类型

function addServerHandler (handler: NitroEventHandler): void

export interface NitroEventHandler {
  handler: string;
  route?: string;
  middleware?: boolean;
  lazy?: boolean;
  method?: string;
}

参数

handler

类型: NitroEventHandler

必需: true

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

  • handler（必需）
    类型: string
    事件处理程序的路径。
  • route（可选）
    类型: string
    路径前缀或路由。如果使用空字符串，将作为中间件使用。
  • middleware（可选）
    类型: boolean
    指定这是一个中间件处理程序。中间件会在每个路由上调用，通常应返回无内容以传递给下一个处理程序。
  • lazy（可选）
    类型: boolean
    使用懒加载导入处理程序。
  • method（可选）
    类型: string
    路由器方法匹配器。如果处理程序名称包含方法名称，则将其用作默认值。

示例

// https://github.com/nuxt-modules/robots
import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options) {
    const resolver = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolver.resolve('./runtime/robots.get.ts')
    })
  }
})

addDevServerHandler

添加一个仅在开发模式下使用的 Nitro 服务器处理程序。该处理程序将从生产构建中排除。

类型

function addDevServerHandler (handler: NitroDevEventHandler): void

export interface NitroDevEventHandler {
  handler: EventHandler;
  route?: string;
}

参数

handler

类型: NitroEventHandler

必需: true

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

  • handler（必需）
    类型: string
    事件处理程序。
  • route（可选）
    类型: string
    路径前缀或路由。如果使用空字符串，将作为中间件使用。

示例

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

export default defineNuxtModule({
  setup() {
    const resolver = createResolver(import.meta.url)

    addDevServerHandler({
      handler: () => {
        return {
          body: `Response generated at ${new Date().toISOString()}`
        }
      },
      route: '/_handler'
    })
  }
})

// https://github.com/nuxt-modules/tailwindcss
import { joinURL } from 'ufo'
import { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'

export default defineNuxtModule({
  async setup(options) {
    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')

    // @ts-ignore
    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 实例配置的更改将不被应用。

类型

function useNitro (): Nitro

export interface Nitro {
  options: NitroOptions;
  scannedHandlers: NitroEventHandler[];
  vfs: Record<string, string>;
  hooks: Hookable<NitroHooks>;
  unimport?: Unimport;
  logger: ConsolaInstance;
  storage: Storage;
  close: () => Promise<void>;
  updateConfig: (config: NitroDynamicConfig) => void | Promise<void>;
}

示例

// https://github.com/nuxt/nuxt/blob/4e05650cde31ca73be4d14b1f0d23c7854008749/packages/nuxt/src/core/nuxt.ts#L404
import { defineNuxtModule, useNitro, addPlugin, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      if (nitro.options.static && nuxt.options.experimental.payloadExtraction === undefined) {
        console.warn('使用实验性有效负载提取以获得全静态输出。您可以通过将 `experimental.payloadExtraction` 设置为 `false` 来选择退出。')
        nuxt.options.experimental.payloadExtraction = true
      }
      nitro.options.replace['process.env.NUXT_PAYLOAD_EXTRACTION'] = String(!!nuxt.options.experimental.payloadExtraction)
      nitro.options._config.replace!['process.env.NUXT_PAYLOAD_EXTRACTION'] = String(!!nuxt.options.experimental.payloadExtraction)

      if (!nuxt.options.dev && nuxt.options.experimental.payloadExtraction) {
        addPlugin(resolver.resolve(nuxt.options.appDir, 'plugins/payload.client'))
      }
    })
  }
})

addServerPlugin

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

您可以在 Nitro 文档 中阅读更多关于 Nitro 插件的信息。

类型

function addServerPlugin (plugin: string): void

参数

plugin

类型: string

必需: true

插件路径。插件必须导出一个接受 Nitro 实例作为参数的函数。

示例

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

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

addPrerenderRoutes

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

类型

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

参数

routes

类型: string | string[]

必需: true

要预渲染的路由或路由数组。

示例

import { defineNuxtModule, addPrerenderRoutes } 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)
    }
  }
})

addServerImportsDir

添加目录以供 Nitro 扫描进行自动导入。

类型

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

参数

dirs

类型: string | string[]

必需: true

要注册供 Nitro 扫描的目录或目录数组

示例

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup(options) {
    const resolver = createResolver(import.meta.url)
    addServerImportsDir(resolver.resolve('./runtime/server/utils'))
  }
})

addServerScanDir

添加要被 Nitro 扫描的目录。它将检查子目录，这些子目录将与 ~/server 文件夹一样注册。

类型

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

参数

dirs

类型: string | string[]

必需: true

要注册以供 Nitro 作为服务器目录扫描的目录或目录数组。

示例

import { defineNuxtModule, createResolver, addServerScanDir } from '@nuxt/kit'
export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup(options) {
    const resolver = createResolver(import.meta.url)
    addServerScanDir(resolver.resolve('./runtime/server'))
  }
})