Re:Nuxt

19/20
Lesson 19

Plugins

執行時插件

本章將帶你了解 Nuxt 的 Plugin 機制，學習如何在 Vue 應用程式初始化時注入全域函數。

1 核心概念

Plugin 的定位

  • •Modules 是在「伺服器啟動時/打包時」運作
  • •Plugins 是在「Vue 應用程式初始化時」運作

主要用途

我們通常利用 Plugin 的 provide 機制，將 helper 函數注入到整個 Nuxt App 中。

語法結構

  • 檔案位置：app/plugins/my-plugin.ts
  • 自動註冊：Nuxt 會自動執行這個資料夾下的檔案。
  • 注入變數：通常我們會加上 $ 前綴（例如 $hello），這是 Vue 生態系的慣例，避免跟普通變數名稱衝突。
export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: (msg: string) => `Hello ${msg}!`
    }
  }
})

這樣你就可以在任何元件透過 $hello('World') 來呼叫它。

2 給 Claude Code 的中文指令 實作練習

我們要製作一個簡單的全域 Helper 函數 $formatPrice，用來把數字轉成金錢格式（例如 1000 → $1,000），並在頁面上測試它。

請幫我建立一個 Nuxt Plugin 並注入全域 Helper 函數：

  1. 建立 app/plugins/format.ts。
  2. 使用 defineNuxtPlugin。
  3. 在回傳物件中使用 provide 注入一個名為 formatPrice 的函數。
  4. 邏輯：接收一個數字，回傳字串。在數字前面加上 $ 符號，並使用 toLocaleString() 來加上千分位逗點 (例如輸入 2000 回傳 '$2,000')。
  5. 建立測試頁面 app/pages/plugin-test.vue：
    • 在 <script setup> 中，使用 const { $formatPrice } = useNuxtApp() 來取得這個函數。
    • 定義一個價格變數 price = 1234567。
    • 在 template 中顯示：原始價格：{{ price }} 和 格式化價格：{{ $formatPrice(price) }}。
  6. 注意：請確保 TypeScript 能正確認識這個注入的函數 (Nuxt 通常會自動處理型別)。

3 驗收重點

請檢查 Claude 完成後的結果：

檔案位置檢查

確認檔案在 app/plugins/format.ts。

功能測試

  1. 打開 http://localhost:3000/plugin-test。
  2. 你應該看到：

原始價格：1234567

格式化價格：$1,234,567

如果看到這個帶有逗號的數字，代表你的 Plugin 已經成功注入到 Vue 實體中了。

使用方式確認

  1. 檢查 plugin-test.vue 的程式碼。
  2. 確認它是透過 useNuxtApp() 拿到 $formatPrice 的。這是在 <script setup> 中的標準用法。

(補充：在 <template> 裡其實可以直接寫 $formatPrice(price) 不用解構，也是可以通的)。

💡 架構師筆記 (.client 與 .server)

Plugin 預設是 Universal (兩邊都跑)。但有些套件（如 jQuery, Leaflet 地圖）會用到 window 或 document 物件，這些在伺服器端 (SSR) 會報錯「window is not defined」。

這時候你可以透過檔名來限制執行環境：

my-plugin.client.ts

只在瀏覽器端跑 (解決 window 報錯問題)。

my-plugin.server.ts

只在伺服器端跑。

建議：對於純粹的 Helper 函數（如日期、金錢格式化），請保留預設值（兩邊都跑），這樣 SSR 出來的 HTML 才會是正確的格式。
19