plugins/ · Nuxt 目录结构

Nuxt 会自动读取 `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` 会被注册。

要在子目录中添加插件，你可以使用 `plugins` 选项，在 `nuxt.config.ts` 中配置

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

观看 Alexander Lichter 关于 Nuxt 插件对象语法的视频。

如果你正在使用对象语法，属性会被静态分析以生成更优化的构建。因此你不应该在运行时定义它们。
例如，设置 `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
  }
})

使用 Composables

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

plugins/hello.ts

export default defineNuxtPlugin((nuxtApp) => {
  const foo = useFoo()
})

但是，请记住，存在一些限制和差异

如果一个 composable 依赖于稍后注册的另一个插件，它可能无法工作。
插件按顺序依次调用，并且在所有其他内容之前调用。你可能会使用一个 composable，它依赖于另一个尚未被调用的插件。

如果一个 composable 依赖于 Vue.js 生命周期，它将无法工作。
通常，Vue.js composables 绑定到当前组件实例，而插件仅绑定到 `nuxtApp` 实例。

提供助手函数

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

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

然后你可以在你的组件中使用这个辅助函数

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 而不是提供辅助函数，以避免污染全局命名空间并保持主 bundle 入口文件的小体积。

如果你的插件提供了一个 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 {}

如果你正在使用 WebStorm，你可能需要增强 @vue/runtime-core，直到这个问题被解决。

Vue 插件

如果你想使用 Vue 插件，例如 vue-gtag 来添加 Google Analytics 标签，你可以使用 Nuxt 插件来实现。

首先，安装 Vue 插件依赖

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

然后创建一个插件文件

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 文档的“自定义指令”中阅读更多信息。

pages

Nuxt 提供了基于文件的路由来在你的 Web 应用程序中创建路由。

public

public/ 目录用于存放你网站的静态资源。