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 實例。

提供 Helpers

如果您想要在 NuxtApp 實例上提供 helper，請從外掛程式中以 provide 鍵回傳它。

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

然後您可以在您的元件中使用 helper

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 而不是提供 helpers，以避免污染全域命名空間並保持您的主 bundle 進入點小巧。

如果您的外掛程式提供 ref 或 computed，它將不會在元件 <template> 中解包裝。
這是由於 Vue 如何處理非模板頂層的 refs。您可以在 Vue 文件中閱讀更多相關資訊。

外掛程式的類型標註

如果您從外掛程式回傳您的 helpers，它們將會自動進行類型標註；您會發現它們已針對 useNuxtApp() 的回傳值以及您的模板中進行類型標註。

如果您需要在另一個外掛程式內部使用提供的 helper，您可以呼叫 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/ 目錄用於提供您網站的靜態資源。