1. 什麼是本地模組？

您可以把本地模組想像成是為您的專案量身打造的專屬擴充包。

當您發現有一組相關的功能（例如，新增了好幾個 API 路由、註冊了一個 Plugin、並提供了一些 Composables），您希望把這些功能整齊地打包在一起時，建立一個本地模組就是最好的選擇。

2. 為什麼要用 `modules/` 資料夾？

這個資料夾最神奇的地方在於自動註冊。

自動發現與啟用

只要您把模組檔案放在 modules/ 資料夾裡，Nuxt 就會自動發現並啟用它，您完全不需要在 nuxt.config.ts 的 modules 陣列中手動加入。

更清晰的專案結構

這能讓您的專案結構更清晰。與其把所有擴充 Nuxt 的邏輯都寫在 nuxt.config.ts 或 plugins/ 裡，不如依照功能，把它們分門別類地整理到不同的本地模組中。

3. 建立一個簡單的 `hello` 模組

讓我們來建立一個簡單的模組，它的功能是自動新增一個 /api/hello-from-module 的 API 路由。

第一步：建立模組檔案

在專案根目錄建立 modules/hello.ts。

modules/hello.ts

// modules/hello.ts
import { defineNuxtModule, addServerHandler, createResolver } from 'nuxt/kit';

export default defineNuxtModule({
  // meta 資訊，方便辨識
  meta: {
    name: 'helloModule'
  },
  // setup 函式是模組的進入點
  setup() {
    console.log('✨ Hello Module is setting up!');

    // 建立一個解析器，方便取得檔案路徑
    const resolver = createResolver(import.meta.url);

    // 使用 nuxt/kit 提供的 addServerHandler 來新增一個伺服器路由
    addServerHandler({
      route: '/api/hello-from-module',
      handler: resolver.resolve('./runtime/api-route.ts') // 處理這個路由的檔案路徑
    });
  }
});

第二步：建立 API 處理函式

接著，建立模組要用到的 API 處理函式。

modules/runtime/api-route.ts

// modules/runtime/api-route.ts
export default defineEventHandler(() => {
  return { message: 'Hello from my custom module!' };
});

今日總結

現在重新啟動您的 Nuxt 專案。您會看到終端機印出 ✨ Hello Module is setting up!，並且您可以直接訪問 /api/hello-from-module，看到 JSON 回應！這一切都是自動完成的。

今天我們學會了使用 modules/ 資料夾來建立本地模組。這是一個非常強大的組織工具，能讓您將複雜的功能打包成一個個獨立、可複用的單元。

專案規模的管理

當您的專案規模越來越大時，善用本地模組來劃分功能，將會讓您的專案保持清晰與高度可維護性。