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

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

addServerHandler

添加 Nitro 服务器处理程序。如果您想创建服务器中间件或自定义路由,请使用此函数。

使用

import { createResolver, defineNuxtModule, addServerHandler } 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 { createResolver, defineNuxtModule, addServerHandler } 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 { createResolver, defineNuxtModule, addDevServerHandler } 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 { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'

export default defineNuxtModule({
  async setup(options, nuxt) {
    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 实例配置的更改不会生效。

使用

import { defineNuxtModule, useNitro } from '@nuxt/kit'

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

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      // 使用 Nitro 实例执行某些操作
    })
  }
})

类型

function useNitro (): Nitro

addServerPlugin

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

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

使用

import { createResolver, defineNuxtModule, addServerPlugin } 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 { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'

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

addPrerenderRoutes

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

使用

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

类型

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

参数

属性类型必需描述
routesstring | string[]true要预渲染的一个路由或路由数组。

addServerImportsDir

添加一个由 Nitro 扫描以进行自动导入的目录。

使用

import { defineNuxtModule, createResolver, addServerImportsDir } 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导入目录的选项。如果 prependtrue,目录将被添加到扫描列表的开头。

示例

您可以使用 addServerImportsDir 添加一个由 Nitro 扫描的目录。这在您希望 Nitro 从自定义服务器目录中自动导入函数时非常有用。

import { defineNuxtModule, createResolver, addServerImportsDir } 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()
  // 使用 apiSecret 执行某些操作
})

addServerScanDir

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

仅扫描 ~/server/api~/server/routes~/server/middleware~/server/utils

使用

import { defineNuxtModule, createResolver, addServerScanDir } 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导入目录的选项。如果 prependtrue,目录将被添加到扫描列表的开头。

示例

您可以使用 addServerScanDir 添加一个由 Nitro 扫描的目录。这在您希望添加自定义服务器目录时非常有用。

import { defineNuxtModule, createResolver, addServerScanDir } 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!
})