Nitro · Nuxt 工具包

Nitro 是一个开源的 TypeScript 框架，用于构建超快速 Web 服务器。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('Using experimental payload extraction for full-static output. You can opt-out by setting `experimental.payloadExtraction` to `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 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'))
  }
})

模板

Nuxt Kit 提供了一组实用工具来帮助您使用模板。这些函数允许您在开发和构建期间生成额外的文件。

解析

Nuxt Kit 提供了一组实用工具来帮助您解析路径。这些函数允许您解析相对于当前模块的路径，具有未知的名称或扩展名。