插件系統

Nuxt 的插件系統允許你在 Vue 應用程式初始化時執行自定義邏輯。這是整合第三方套件（如 Google Analytics、i18n）或注入全域 Helper 的最佳場所。

核心概念

Nuxt 會自動讀取 plugins/ 目錄下的檔案，並在應用程式建立時執行它們。插件是連接 Nuxt 核心與外部邏輯的橋樑。

Initialization Lifecycle

App Created

Run

Plugins

Mounted

執行模式

你可以透過檔案名稱後綴來控制插件的執行環境。

Plugins Directory

plugins/
- setup.tsUniversal
- analytics.client.tsClient
- db.server.tsServer

Universal (預設)

在伺服器端與客戶端都會執行。適用於大多數場景，如註冊全域 Helper 或設定共用狀態。

Client Only

只在瀏覽器端執行。適用於存取 window、document 或整合純前端套件。

Server Only

只在伺服器端執行。適用於初始化資料庫連線、讀取敏感檔案或處理 Secret Keys。

注入 Helper

你可以透過回傳 provide 物件，將 Helper 函式注入到整個應用程式中。 Nuxt 會自動為其加上 $ 前綴。

定義插件

plugins/hello.ts

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

在元件中使用

app.vue

<script setup>
// 在 script 中使用
const { $hello } = useNuxtApp()
console.log($hello('World'))
</script>

<template>
  <!-- 在 template 中直接使用 -->
  <div>{{ $hello('Nuxt') }}</div>
</template>

實驗室：Toast Plugin

這個範例模擬了一個 $toast 插件。點擊按鈕，觀察插件如何被呼叫並在介面上顯示通知。

localhost:3000

My Nuxt App

Click buttons to trigger the injected plugin.

plugins/toast.ts

export default defineNuxtPlugin(() => {
  return {
    provide: {
      toast: {
        success: (msg) => { ... },
        error: (msg) => { ... }
      }
    }
  }
})

Console

No events yet...

整合 Vue 插件

如果你需要使用傳統的 Vue 插件（如 i18n, Vuetify, Element Plus），可以在 Nuxt 插件中存取 vueApp 實例。

plugins/i18n.ts

import { createI18n } from 'vue-i18n'

export default defineNuxtPlugin((nuxtApp) => {
  const i18n = createI18n({
    locale: 'en',
    messages: {
      en: { welcome: 'Welcome!' },
      zh: { welcome: '歡迎！' }
    }
  })

  // 註冊 Vue 插件
  nuxtApp.vueApp.use(i18n)
})

Nuxt 插件的參數 nuxtApp 包含了 vueApp 屬性，這就是標準的 Vue Application Instance。