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 鉤子之後呼叫 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 文件.
中閱讀有關 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 中可用，而無需手動匯入它們。

使用

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