plugins

Nuxt 拥有一个插件系统，允许你在创建 Vue 应用时使用 Vue 插件以及更多功能。

Nuxt 会自动读取 app/plugins/ 目录中的文件，并在创建 Vue 应用时加载它们。

里面的所有插件都是自动注册的，你不需要将它们单独添加到 nuxt.config 中。
你可以在文件名中使用 .server 或 .client 后缀，以使插件仅在服务端或客户端加载。

已注册的插件

只有目录顶层的文件（或任何子目录中的 index 文件）才会自动注册为插件。

目录结构
-| plugins/
---| foo.ts      // scanned
---| bar/
-----| baz.ts    // not scanned
-----| foz.vue   // not scanned
-----| index.ts  // currently scanned but deprecated

只有 foo.ts 和 bar/index.ts 会被注册。

若要在子目录中添加插件，你可以在 nuxt.config.ts 中使用 app/plugins 选项

nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    '~/plugins/bar/baz',
    '~/plugins/bar/foz',
  ],
})

创建插件

传递给插件的唯一参数是 nuxtApp。

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // Doing something with nuxtApp
})

对象语法插件

对于更高级的用例，也可以使用对象语法来定义插件。例如

plugins/hello.ts
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre', // or 'post'
  async setup (nuxtApp) {
    // this is the equivalent of a normal functional plugin
  },
  hooks: {
    // You can directly register Nuxt app runtime hooks here
    'app:created' () {
      const nuxtApp = useNuxtApp()
      // do something in the hook
    },
  },
  env: {
    // Set this value to `false` if you don't want the plugin to run when rendering server-only or island components.
    islands: true,
  },
})
如果你使用对象语法，属性将会被静态分析以生成更优化的构建。因此，你不应该在运行时定义它们。
例如，设置 enforce: import.meta.server ? 'pre' : 'post' 将破坏 Nuxt 为你的插件能够做的任何未来优化。在使用对象语法时，Nuxt 会静态预加载所有钩子监听器，允许你定义钩子而无需担心插件注册的顺序。

注册顺序

你可以通过在文件名中加“字母顺序”编号前缀来控制插件的注册顺序。

目录结构
plugins/
 | - 01.myPlugin.ts
 | - 02.myOtherPlugin.ts

在这个例子中， 02.myOtherPlugin.ts 将能够访问由 01.myPlugin.ts 注入的任何内容。

这在你有依赖于另一个插件的插件时非常有用。

如果你对“字母顺序”编号还不熟悉，请记住文件名是作为字符串排序的，而不是作为数值。例如， 10.myPlugin.ts 会排在 2.myOtherPlugin.ts 前面。这就是为什么示例在个位数前加了 0 前缀的原因。

加载策略

并行插件

默认情况下，Nuxt 按顺序加载插件。你可以将插件定义为 parallel，这样 Nuxt 就不会等到该插件执行完毕才加载下一个插件。

plugins/my-plugin.ts
export default defineNuxtPlugin({
  name: 'my-plugin',
  parallel: true,
  async setup (nuxtApp) {
    // the next plugin will be executed immediately
  },
})

带有依赖的插件

如果一个插件在运行前需要等待另一个插件，你可以将该插件的名称添加到 dependsOn 数组中。

plugins/depending-on-my-plugin.ts
export default defineNuxtPlugin({
  name: 'depends-on-my-plugin',
  dependsOn: ['my-plugin'],
  async setup (nuxtApp) {
    // this plugin will wait for the end of `my-plugin`'s execution before it runs
  },
})

使用组合式函数

你可以在 Nuxt 插件中使用 composables 以及 utils

app/plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  const foo = useFoo()
})

但是，请记住存在一些限制和区别

如果一个组合式函数依赖于稍后注册的另一个插件，它可能无法正常工作。
插件按顺序依次调用，并且在其他所有事情之前执行。你可能会使用一个组合式函数，它依赖于另一个尚未被调用的插件。
如果一个组合式函数依赖于 Vue.js 生命周期，它将无法工作。
通常，Vue.js 组合式函数绑定到当前的组件实例，而插件仅绑定到 nuxtApp 实例。

提供辅助方法

如果你想在 NuxtApp 实例上提供一个辅助方法，请从插件中通过 provide 键返回它。

export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: (msg: string) => `Hello ${msg}!`,
    },
  }
})

然后你可以在组件中使用这个辅助方法

app/components/Hello.vue
<script setup lang="ts">
// alternatively, you can also use it here
const { $hello } = useNuxtApp()
</script>

<template>
  <div>
    {{ $hello('world') }}
  </div>
</template>
请注意，我们强烈建议使用 composables 而不是提供辅助方法，以避免污染全局命名空间并保持你的主包体积较小。
如果你的插件提供了一个 ref 或 computed，它不会在组件的 <template> 中自动解包。
这是由于 Vue 处理非模板顶层 ref 的方式所致。你可以在 Vue 文档中阅读更多相关信息。

为插件添加类型

如果你从插件中返回辅助方法，它们将自动获得类型；你会在 useNuxtApp() 的返回值中以及你的模板内找到它们的类型。

如果你需要在另一个插件内部使用所提供的辅助方法，你可以调用 useNuxtApp() 来获取带有类型的版本。但总的来说，除非你确定插件的执行顺序，否则应避免这样做。

对于高级用例，你可以像这样声明注入属性的类型

index.d.ts
declare module '#app' {
  interface NuxtApp {
    $hello (msg: string): string
  }
}

declare module 'vue' {
  interface ComponentCustomProperties {
    $hello (msg: string): string
  }
}

export {}

Vue 插件

如果你想使用 Vue 插件（例如使用 vue-gtag 添加 Google Analytics 标签），你可以通过 Nuxt 插件来做到这一点。

首先，安装 Vue 插件依赖

npm install --save-dev vue-gtag-next

然后创建一个插件文件

app/plugins/vue-gtag.client.ts
import VueGtag, { trackRouter } from 'vue-gtag-next'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueGtag, {
    property: {
      id: 'GA_MEASUREMENT_ID',
    },
  })
  trackRouter(useRouter())
})

Vue 指令

同样地，你可以在插件中注册自定义的 Vue 指令。

plugins/my-directive.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.directive('focus', {
    mounted (el) {
      el.focus()
    },
    getSSRProps (binding, vnode) {
      // you can provide SSR-specific props here
      return {}
    },
  })
})
如果你注册了一个 Vue 指令，你必须在客户端和服务端都对其进行注册，除非你只在渲染单侧时使用它。如果该指令仅在客户端有意义，你可以将其移动到 ~/plugins/my-directive.client.ts，并在 ~/plugins/my-directive.server.ts 中为服务端提供一个“存根”（stub）指令。
阅读更多内容请参阅 Vue 文档中的自定义指令。