v3.16
Nuxt on GitHub

插件

源代码
Nuxt Kit 提供了一组实用工具，帮助你创建和使用插件。你可以使用这些函数为你的模块添加插件或插件模板。

插件是自包含的代码，通常为 Vue 添加应用级功能。在 Nuxt 中，插件会从 plugins 目录自动导入。然而，如果你需要在模块中提供插件，Nuxt Kit 提供了 addPlugin 和 addPluginTemplate 方法。这些工具允许你自定义插件配置，以更好地满足你的需求。

addPlugin

注册一个 Nuxt 插件并添加到插件数组。

观看 Vue School 关于 addPlugin 的视频。

类型

function addPlugin (plugin: NuxtPlugin | string, options: AddPluginOptions): NuxtPlugin

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

interface AddPluginOptions { append?: boolean }

参数

plugin

类型: NuxtPlugin | string

必填: true

插件对象或插件路径字符串。如果提供字符串，将转换为插件对象，并将 src 设置为该字符串值。如果提供插件对象，必须具有以下属性：

  • src（必填）
    类型: string
    插件路径。
  • mode（可选）
    类型: 'all' | 'server' | 'client'
    默认值: 'all'
    如果设置为 'all'，插件将包含在客户端和服务端打包中。如果设置为 'server'，插件仅包含在服务端打包中。如果设置为 'client'，插件仅包含在客户端打包中。你还可以在指定 src 选项时使用 .client 和 .server 修饰符，以仅在客户端或服务端使用插件。
  • order（可选）
    类型: number
    默认值: 0
    插件的顺序。此属性允许更精细地控制插件顺序，仅限高级用户使用。数值越小越先执行，用户插件默认为 0。建议将 order 设置为 -20（用于前置插件，在 Nuxt 插件之前运行）到 20（用于后置插件，在 Nuxt 插件之后运行）之间的数字。
除非你清楚自己在做什么，否则不要使用 order。对于大多数插件，默认的 order 值 0 已足够。若要将插件追加到插件数组末尾，请使用 append 选项。

options

类型: AddPluginOptions

默认值: {}

传递给插件的选项。如果 append 设置为 true，插件将追加到插件数组末尾，而不是前置。

示例

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

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

    addPlugin({
      src: resolver.resolve('runtime/plugin.js'),
      mode: 'client'
    })
  }
})

addPluginTemplate

添加模板并注册为 Nuxt 插件。这对于需要在构建时生成代码的插件非常有用。

观看 Vue School 关于 addPluginTemplate 的视频。

类型

function addPluginTemplate (pluginOptions: NuxtPluginTemplate, options: AddPluginOptions): NuxtPlugin

interface NuxtPluginTemplate<Options = Record<string, any>> {
  src?: string,
  filename?: string,
  dst?: string,
  mode?: 'all' | 'server' | 'client',
  options?: Options,
  getContents?: (data: Options) => string | Promise<string>,
  write?: boolean,
  order?: number
}

interface AddPluginOptions { append?: boolean }

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

参数

pluginOptions

类型: NuxtPluginTemplate

必填: true

插件模板对象，包含以下属性：

  • src（可选）
    类型: string
    模板路径。如果未提供 src，则必须提供 getContents。
  • filename（可选）
    类型: string
    模板文件名。如果未提供 filename，将根据 src 路径生成。在这种情况下，src 选项为必填。
  • dst（可选）
    类型: string
    目标文件路径。如果未提供 dst，将根据 filename 路径和 Nuxt 的 buildDir 选项生成。
  • mode（可选）
    类型: 'all' | 'server' | 'client'
    默认值: 'all'
    如果设置为 'all'，插件将包含在客户端和服务端打包中。如果设置为 'server'，插件仅包含在服务端打包中。如果设置为 'client'，插件仅包含在客户端打包中。你还可以在指定 src 选项时使用 .client 和 .server 修饰符，以仅在客户端或服务端使用插件。
  • options（可选）
    类型: Options
    传递给模板的选项。
  • getContents（可选）
    类型: (data: Options) => string | Promise<string>
    一个函数，将使用 options 对象调用。它应返回一个字符串或解析为字符串的 Promise。如果提供了 src，此函数将被忽略。
  • write（可选）
    类型: boolean
    如果设置为 true，模板将被写入目标文件。否则，模板仅在虚拟文件系统中使用。
  • order（可选）
    类型: number
    默认值: 0
    插件的顺序。此属性允许更精细地控制插件顺序，仅限高级用户使用。数值越小越先执行，用户插件默认为 0。建议将 order 设置为 -20（用于前置插件，在 Nuxt 插件之前运行）到 20（用于后置插件，在 Nuxt 插件之后运行）之间的数字。
除非你清楚自己在做什么，否则不要使用 order。对于大多数插件，默认的 order 值 0 已足够。若要将插件追加到插件数组末尾，请使用 append 选项。

options

类型: AddPluginOptions

默认值: {}

传递给插件的选项。如果 append 设置为 true，插件将追加到插件数组末尾，而不是前置。

示例

// https://github.com/vuejs/vuefire
import { createResolver, defineNuxtModule, addPluginTemplate } from '@nuxt/kit'

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

    addPluginTemplate({
      src: resolve(templatesDir, 'plugin.ejs'),
      filename: 'plugin.mjs',
      options: {
        ...options,
        ssr: nuxt.options.ssr,
      },
    })
  }
})