v3.17

Nitro

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

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

¥Nitro is an open source TypeScript framework to build ultra-fast web servers. Nuxt uses Nitro as its server engine. You can use useNitro to access the Nitro instance, addServerHandler to add a server handler, addDevServerHandler to add a server handler to be used only in development mode, addServerPlugin to add a plugin to extend Nitro's runtime behavior, and addPrerenderRoutes to add routes to be prerendered by Nitro.

addServerHandler

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

¥Adds a nitro server handler. Use it if you want to create server middleware or custom route.

类型

¥Type

function addServerHandler (handler: NitroEventHandler): void

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

参数

¥Parameters

handler

类型：NitroEventHandler

¥Type: NitroEventHandler

必需：true

¥Required: true

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

¥A handler object with the following properties:

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

示例

¥Examples

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

addDevServerHandler

添加一个 nitro 服务器处理程序，仅在开发模式下使用。此处理程序将被排除在生产构建之外。

¥Adds a nitro server handler to be used only in development mode. This handler will be excluded from production build.

类型

¥Type

function addDevServerHandler (handler: NitroDevEventHandler): void

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

参数

¥Parameters

handler

类型：NitroEventHandler

¥Type: NitroEventHandler

必需：true

¥Required: true

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

¥A handler object with the following properties:

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

示例

¥Examples

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 实例。

¥Returns the Nitro instance.

你只能在 ready 钩子之后调用 useNitro()。¥You can call useNitro() only after ready hook.
不会应用对 Nitro 实例配置的更改。

类型

¥Type

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>;
}

示例

¥Examples

// 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 的运行时行为。

¥Add plugin to extend Nitro's runtime behavior.

你可以在 Nitro documentation 中阅读有关 Nitro 插件的更多信息。

类型

¥Type

function addServerPlugin (plugin: string): void

参数

¥Parameters

plugin

类型：string

¥Type: string

必需：true

¥Required: true

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

¥Path to the plugin. The plugin must export a function that accepts Nitro instance as an argument.

示例

¥Examples

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 的路由。

¥Add routes to be prerendered to Nitro.

类型

¥Type

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

参数

¥Parameters

routes

类型：string | string[]

¥Type: string | string[]

必需：true

¥Required: true

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

¥A route or an array of routes to prerender.

示例

¥Examples

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 扫描其自动导入。

¥Add a directory to be scanned for auto-imports by Nitro.

类型

¥Type

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

参数

¥Parameters

dirs

类型：string | string[]

¥Type: string | string[]

必需：true

¥Required: true

注册为 Nitro 扫描的目录或目录数组

¥A directory or an array of directories to register to be scanned by Nitro

示例

¥Examples

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 文件夹一样进行注册。

¥Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered just like the ~/server folder is.

类型

¥Type

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

参数

¥Parameters

dirs

类型：string | string[]

¥Type: string | string[]

必需：true

¥Required: true

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

¥A directory or an array of directories to register to be scanned for by Nitro as server dirs.

示例

¥Examples

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