vue-patterns

Vue.js 模式與最佳實踐

使用 Composition API (<script setup>) 進行 Vue.js 3 開發的全面指南，涵蓋元件設計、響應式、狀態管理、路由、測試和 SSR 模式。其中也包含了與一般 Vue 不同的 Nuxt 專用指引。

啟用時機

當以下情況發生時啟用此技能：

• 專案使用了 Vue.js (任何版本)、Nuxt、Vite + Vue 或 Pinia。
• 使用者詢問關於 Vue 元件架構、Composable、響應式或狀態管理。
• 正在審查 Vue 單一檔案元件 (.vue 檔案)。
• 正在設定 Vue Router、Pinia stores 或 Vite/Vitest 配置。
• 討論 Vue 特定的效能、安全性或 SSR 模式。

---

1. 專案結構

推薦佈局 (以功能為優先)

src/
├── api/              # API 客戶端與端點定義
├── assets/           # 靜態資源 (圖片、字體、圖標)
├── components/       # 共用/可複用元件
│   ├── base/         # 基礎 UI 元件 (Button, Input, Modal)
│   └── features/     # 特定功能的共用元件
├── composables/      # 可複用的 Composition API 邏輯
├── layouts/          # 頁面佈局 (可選)
├── pages/            # 路由層級的頁面元件
├── router/           # Vue Router 配置
├── stores/           # Pinia stores
├── types/            # TypeScript 類型定義
├── utils/            # 純工具函數
└── App.vue           # 根元件

檔案命名

慣例	使用時機
PascalCase.vue	所有元件 (由 vue/multi-word-component-names 強制執行)
useCamelCase.ts	Composables
camelCase.ts	工具、API 客戶端、類型
kebab-case 目錄	路由區段、功能資料夾

---

2. 元件架構

單一檔案元件順序

<script setup lang="ts">
// 1. 導入 (vue → 生態系 → 絕對路徑 → 相對路徑)
// 2. Props & Emits & Slots
// 3. Composables
// 4. 本地狀態 (ref/reactive)
// 5. 計算屬性
// 6. 方法
// 7. 監聽器
// 8. 生命週期鉤子
</script>

<template>
  <!-- 模板內容 -->
</template>

<style scoped>
  /* 作用域樣式 */
</style>

展示層 vs 容器層元件

• 容器元件：負責資料擷取、狀態和副作用。渲染展示層元件。
• 展示層元件：接收 props，觸發事件。不進行 API 呼叫，不存取 store。純渲染。

Props 最佳實踐

// 基於類型的 Props 與預設值
interface Props {
  label: string;
  variant?: "primary" | "secondary";
  disabled?: boolean;
  items: Item[];
}

const props = withDefaults(defineProps<Props>(), {
  variant: "primary",
  disabled: false,
});

• 始終提供 type，並在適當時提供 required/default。
• 布林 Props：使用 isXxx、hasXxx、canXxx。
• 永遠不要直接修改 props — 應改用觸發事件的方式。
• 對於 v-model 綁定，請使用 defineModel() (Vue 3.4+) 或 modelValue + update:modelValue。

事件

const emit = defineEmits<{
  submit: [];
  "update:modelValue": [value: string];
  select: [id: string, index: number];
}>();

• 在模板中使用 kebab-case (@update:model-value)。
• 在 script 中使用 camelCase (emit("update:modelValue", val))。

---

3. Composables (可複用邏輯)

結構

// composables/useDebounce.ts
export function useDebounce<T>(value: MaybeRef<T>, delay: number): Ref<T> {
  const debounced = ref(toValue(value)) as Ref<T>;

  let timer: ReturnType<typeof setTimeout>;
  watch(
    () => toValue(value),
    (newVal) => {
      clearTimeout(timer);
      timer = setTimeout(() => { debounced.value = newVal; }, delay);
    }
  );

  onUnmounted(() => clearTimeout(timer));
  return readonly(debounced);
}

規則

• 必須以 use 前綴開頭。
• 回傳響應式值 (ref、computed、reactive)，永遠不要回傳純原始型別。
• 透過 MaybeRef / toRef() / toValue() 接受響應式輸入。
• 在 onUnmounted 或監聽器的 onCleanup 中清理副作用。
• 沒有模組層級的副作用。

vs Mixins

Composables 完全取代了 Vue 2 的 mixins：

• Mixins：資料流向不透明、來源衝突、命名衝突。
• Composables：明確的導入、清晰的回傳值、可組合且可進行樹搖最佳化。

---

4. 狀態管理

何時使用何種模式

模式	使用場景
ref() / reactive()	本地元件狀態
Props + Emits	父子元件通訊
Provide / Inject	主題、配置、插件 API
Pinia store	全域、共用、複雜狀態
伺服器狀態 Composable	帶有快取的 API 資料 (包裝 fetch/TanStack Query)

Pinia Setup Store (偏好方式)

// stores/useCartStore.ts
export const useCartStore = defineStore("cart", () => {
  const items = ref<CartItem[]>([]);
  const isLoading = ref(false);

  const totalPrice = computed(() =>
    items.value.reduce((sum, i) => sum + i.price * i.quantity, 0)
  );
  const itemCount = computed(() =>
    items.value.reduce((sum, i) => sum + i.quantity, 0)
  );

  async function addItem(productId: string) {
    isLoading.value = true;
    try {
      const item = await fetchProduct(productId);
      const existing = items.value.find(i => i.id === item.id);
      if (existing) existing.quantity++;
      else items.value.push({ ...item, quantity: 1 });
    } finally {
      isLoading.value = false;
    }
  }

  return { items, isLoading, totalPrice, itemCount, addItem };
});

• 使用 Setup Store 語法 (而非 Options Store)。
• 偏好使用 actions 進行業務層級的變更，並使用 $patch() 進行分組更新。
• 每個非同步 action：處理 loading + success + error。

---

5. Vue Router

路由定義

const routes = [
  {
    path: "/users/:id",
    name: "user-detail",
    component: () => import("@/pages/UserDetail.vue"), // 懶加載
    props: true, // 將參數作為 props 傳遞
    meta: { requiresAuth: true },
  },
];

導航守衛

router.beforeEach((to, from) => {
  const { isLoggedIn } = useAuthStore();
  if (to.meta.requiresAuth && !isLoggedIn) {
    return { name: "login", query: { redirect: to.fullPath } };
  }
});

響應式路由參數

當元件保持掛載但路由參數改變時：

const route = useRoute();
const id = computed(() => route.params.id as string);
watch(id, (newId) => fetchItem(newId));

---

6. 模板模式

模板語法

<!-- v-if/v-else-if/v-else -->
<div v-if="isLoading">載入中...</div>
<div v-else-if="error">錯誤：{{ error }}</div>
<div v-else>{{ content }}</div>

<!-- v-show 用於頻繁切換 -->
<div v-show="isOpen">切換的內容</div>

<!-- 帶有穩定 key 的 v-for -->
<div v-for="item in items" :key="item.id">{{ item.name }}</div>

<!-- 使用計算屬性過濾後的列表 (不在同一元素上使用 v-if + v-for) -->
<div v-for="item in activeItems" :key="item.id">{{ item.name }}</div>

<!-- 事件處理 -->
<form @submit.prevent="handleSubmit">
  <button type="submit">儲存</button>
</form>

<!-- v-model -->
<input v-model="name" />
<CustomInput v-model="value" v-model:title="title" />

---

7. 效能

技術	使用時機
v-memo	很少變更的列表項目
v-once	只渲染一次且永遠靜態的內容
shallowRef()	會被整體替換的大型資料結構
shallowReactive()	只有頂層屬性是響應式的
v-show 優於 v-if	頻繁的可見性切換
<KeepAlive :max="10">	快取被切換的視圖
懶加載路由	非關鍵路由使用 () => import(...)
Suspense	非同步元件載入，搭配 fallback

---

8. 測試

技術棧

• Vitest 用於單元測試和元件測試
• Vue Test Utils 用於掛載和互動
• @pinia/testing 用於 store 模擬
• Playwright 用於端到端測試

元件測試模式

import { mount } from "@vue/test-utils";
import { createPinia, setActivePinia } from "pinia";
import UserCard from "./UserCard.vue";

beforeEach(() => { setActivePinia(createPinia()); });

it("渲染並觸發事件", async () => {
  const wrapper = mount(UserCard, {
    props: { user: { id: "1", name: "Alice" } },
  });
  expect(wrapper.text()).toContain("Alice");
  await wrapper.find("button").trigger("click");
  expect(wrapper.emitted("select")![0]).toEqual(["1"]);
});

---

9. Nuxt 特定模式

自動導入

Nuxt 自動導入 ref、computed、watch、useFetch、useAsyncData 等。直接使用它們而無需導入。對於非 Nuxt 專案，請始終明確導入。

useAsyncData / useFetch

const { data: user, pending, error, refresh } = await useAsyncData(
  "user", // 用於快取的唯一鍵值
  () => $fetch(`/api/users/${id}`),
);

const { data: posts } = await useFetch("/api/posts", {
  query: { page: 1 },
  key: "posts-page-1", // 用於請求去重
});

伺服器路由

// server/api/users/[id].ts
export default defineEventHandler(async (event) => {
  const { id } = await getValidatedRouterParams(event, z.object({
    id: z.string().uuid(),
  }).parse);
  // ... 擷取並回傳
});

執行環境配置

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 僅服務端
    apiSecret: "",
    // 公開的 (暴露給客戶端)
    public: {
      apiBase: "https://api.example.com",
    },
  },
});

---

10. Vue 3.5+ 新 API

響應式 Props 解構

Vue 3.5 穩定了響應式 props 解構 — 從 defineProps() 解構的變數會自動成為響應式：

// Vue 3.5+: 解構的 props 是響應式的 (無需使用 toRefs)
const { count = 0, msg = "hello" } = defineProps<{
  count?: number;
  msg?: string;
}>();

// 限制：無法直接監聽解構後的 prop
watch(() => count, (newVal) => { ... }); // 透過 getter 是必要的

useTemplateRef()

使用 useTemplateRef() 取代名稱匹配的純 ref 來獲取模板引用：

import { useTemplateRef } from "vue";
const inputEl = useTemplateRef<HTMLInputElement>("input");
// "input" 匹配模板中的 ref="input" 屬性，而非變數名稱

支援動態 ref ID：useTemplateRef(dynamicRefId)。

onWatcherCleanup()

全域可導入的監聽器清理 API (Vue 3.5+)。必須在監聽器回調內部同步呼叫：

import { watch, onWatcherCleanup } from "vue";

watch(userId, async (newId) => {
  const controller = new AbortController();
  onWatcherCleanup(() => controller.abort());
  // ... 使用 signal 進行擷取
});

useId()

SSR 穩定的唯一 ID 生成器，用於表單元素和無障礙性：

import { useId } from "vue";
const id = useId();

defer Teleport

<Teleport defer> 允許傳送至在同一個週期內渲染的目標：

<Teleport defer to="#container">內容</Teleport>
<div id="container"></div>

懶加載水合 (SSR)

defineAsyncComponent() 現在支援 hydrate 策略：

import { defineAsyncComponent, hydrateOnVisible } from "vue";
const AsyncComp = defineAsyncComponent({
  loader: () => import("./Comp.vue"),
  hydrate: hydrateOnVisible(),
});

---

反模式

反模式	為什麼是錯的	修正方式
解構 defineProps() (Vue < 3.5)	取得快照，失去響應性	透過 props.xxx 存取或使用 toRefs()
watch() 監聽解構後的 prop (Vue 3.5+)	編譯時錯誤 — 解構後的 props 無法直接被監聽	使用 getter 包裝：watch(() => count, ...)
在同一元素上使用 v-if + v-for	執行順序不明確	使用計算屬性過濾後的陣列
v-for 的 key 使用 index	重新排序時狀態錯亂	使用穩定的資料庫 ID
修改 props	違反單向資料流	觸發事件或使用 v-model
v-html 搭配使用者內容	XSS 漏洞	使用 DOMPurify 進行消毒
在 Vue 3 中使用 Mixins	不透明、易衝突	改用 Composables
Composables 中的模組層級副作用	在多個實例間共用	範圍限制在 onMounted + onUnmounted 內
對可替換的狀態使用 reactive()	替換會破壞響應性	改用 ref()
沒有清理的監聽器	記憶體洩漏、競爭條件	使用 onCleanup 或 onWatcherCleanup() (Vue 3.5+)
在新的 Vue 3 程式碼中使用 Options API	生態系已轉向 Composition API	使用 <script setup>
對模板引用使用純 ref	不支援動態 ref，名稱匹配不穩定	改用 useTemplateRef() (Vue 3.5+)

相關技能

• accessibility — ARIA、語意化 HTML、焦點管理
• frontend-patterns — 跨框架的前端架構
• typescript — 應用於 Vue 專案的 TypeScript 最佳實踐
• coding-standards — 通用程式碼品質標準