Nitro

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: 一个处理器对象，包含以下属性：

属性	类型	是否必须	说明
`handler`	`string`	`true`	事件处理器的路径。
`route`	`string`	`false`	路径前缀或路由。如果使用空字符串，则作为中间件使用。
`middleware`	`boolean`	`false`	指定该处理器是中间件。中间件会在所有路由上调用，通常应返回空以传递给下一个处理器。
`lazy`	`boolean`	`false`	使用延迟加载导入处理器。当你只想按需加载处理器时，这个很有用。
`method`	`string`	`false`	路由方法匹配器。如果处理器名称包含方法名，会被用作默认值。

示例

基本用法

你可以使用 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')
    })
  }
})

export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`
  }
})

访问 /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: 一个处理器对象，包含以下属性：

属性	类型	是否必须	说明
`handler`	`EventHandler`	`true`	事件处理器。
`route`	`string`	`false`	路径前缀或路由。如果使用空字符串，则作为中间件使用。

示例

基本用法

有时，你可能想创建一个仅供开发使用的服务器处理器，例如 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

参数

属性	类型	是否必须	说明
`plugin`	`string`	`true`	插件路径。插件必须默认导出一个函数，该函数接受 Nitro 实例作为参数。

示例

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

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

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook("request", (event) => {
    console.log("on request", event.path);
  });

  nitroApp.hooks.hook("beforeResponse", (event, { body }) => {
    console.log("on response", event.path, { body });
  });

  nitroApp.hooks.hook("afterResponse", (event, { body }) => {
    console.log("on after response", event.path, { body });
  });
});

`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

参数

属性	类型	是否必须	说明
`routes`	`string \| 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

参数

属性	类型	是否必须	说明
`dirs`	`string \| string[]`	`true`	一个目录或目录数组，注册后由 Nitro 扫描以自动导入。
`opts`	`{ prepend?: boolean }`	`false`	导入目录的选项。如果 `prepend` 为 `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'))
  }
})

export function useApiSecret() {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}

然后你可以在服务器代码中使用 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

参数

属性	类型	是否必须	说明
`dirs`	`string \| string[]`	`true`	一个目录或目录数组，注册后由 Nitro 扫描为服务器目录。
`opts`	`{ prepend?: boolean }`	`false`	导入目录的选项。如果 `prepend` 为 `true`，则将目录添加到扫描列表的前面。

示例

你可以使用 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'))
  }
})

export function hello() {
  return 'Hello from server utils!'
}

然后你可以在服务器代码中使用 hello 函数。

runtime/server/api/hello.ts

export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})

Was this helpful?

报告问题或者在 GitHub 上编辑此页面

模板

Nuxt Kit 提供了一组工具，帮助你处理模板。这些函数允许你在开发和构建时生成额外的文件。

解析路径

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