---
# System prepended metadata

title: "\U0001F9F0 Vue + Vite 前端專案初始化全"
tags: [環境相關]

---

# 🧰 Vue + Vite 前端專案初始化全

🔖 整合來源：

* [《🧰 專案初始化流程總覽：讓專案跑得起來的第一步》](https://hackmd.io/@63Ywhax5TLKtGhFSWnacvQ/By4uDI5rex)
* [《🧰 Vue + Vite 專案初始化流程指南》](https://hackmd.io/@63Ywhax5TLKtGhFSWnacvQ/SJhwwIqHlx)

---

## 🧱 一、專案初始化概念與工具總覽

📌 來源整合：〈總覽〉 + 〈指南〉

建立一個完整的 Vue 前端專案，從來不只是打開 VSCode 開始寫畫面而已。實務上，開發前的第一步，是要幫整個專案鋪好「能跑起來的環境」，這件事稱為「專案初始化」。

這個過程不僅包含 Vite + Vue 的骨架建立，還包括環境變數 `.env` 設定、Node.js 的後端模擬、開發用工具（如 ESLint / Prettier / 插件懶人註冊）的安裝、UI 套件整合、Router 與 Store 的啟用等。

這份筆記會幫你：

1. 🎯 從頭到尾建立一個 Vue + Vite 的可執行專案
2. 🧩 裝好「開發好用工具」與「UI 套件」
3. 🗂 建立清楚的資料夾結構與 main.js 啟動流程
4. 🔧 串接 API 並處理跨域（含 axios 與 proxy）
5. 🛠 延伸進階懶人工具與動畫／互動元件

---

### 🔍 開發環境的三大層次概念（出自〈總覽〉）

| 層次            | 說明與重點                                                     |
| ------------- | --------------------------------------------------------- |
| 🧱 專案骨架       | 使用 Vite 建立 Vue 專案、初始化資料夾、安裝 router 等基本依賴                  |
| 🛠 開發效率工具包    | 安裝實用工具（如 ESLint、Prettier、auto-import、vite-plugin-inspect） |
| 🎨 UI 套件與樣式整合 | PrimeVue（或其他框架）整合與樣式引入                                    |

---

### 📦 開箱即用的初始化觀念

* 每個 UI 框架幫你做的事情不一樣，要去比對官方文件看它幫你處理了什麼
* `main.js` 是 Vue 專案的大腦，「整合插件與樣式的總司令」
* `.env` 是前後端協作中極其重要的橋梁
* 懶人工具 ≠ 懶惰，是讓你專注邏輯與維護效率的超級助力

---

## 🪜 二、Vue + Vite 初始化流程步驟

📌 來源整合：〈指南〉主幹 + 〈總覽〉補充細節

這一區塊是從零開始建立 Vue + Vite 專案的流程，包含建立前端專案骨架、初始化 Node 環境、設定 `.env` 檔與 `.gitignore`，並安裝 `vue-router` 路由功能。

---

### Step 1️⃣ 建立 Vue + Vite 專案骨架

透過 Vite 提供的快速初始化指令建立新專案：

```bash
npm create vite@latest
```

依照指示輸入：

```
✔ Project name: » vite-project（← 你想要的專案名稱）
✔ Select a framework: » Vue
✔ Select a variant: » JavaScript
```

然後進入資料夾並安裝：

```bash
cd vite-project
npm install
```

---

### Step 2️⃣ 初始化 Node 環境（模擬後端或搭配 Express）

雖然主軸是前端，但實務開發一定會串接 API，建議一併初始化 Node 專案與常用工具：

```bash
npm init --yes
npm i -D nodemon
```

📌 `nodemon`：自動偵測檔案變動，自動重啟伺服器，開發後端 Express API 時超好用。

---

### Step 3️⃣ 建立 `.env` 與 `.gitignore`

這兩個不是自動生成，要你手動建立。

#### 📝 `.env`：放環境變數（API 路徑、port 等）

```dotenv
PORT=3000
VITE_API_BASE_URL=http://localhost:3000
```

📌 注意：**只有以 `VITE_` 開頭的變數才能被前端讀取！**

---

#### 📝 `.gitignore`：讓 Git 忽略不該上傳的內容

```gitignore
.env
node_modules
dump/*
!dump/.gitkeep
```

📌 `.gitkeep` 是一個技巧，用來保留空資料夾（Git 預設不會追蹤空資料夾）。

---

### Step 4️⃣ 安裝 Vue Router 並建立基本路由設定

```bash
npm i vue-router
```

建立檔案：

```
src/router/index.js
src/views/HomeView.vue
```

`router/index.js` 範例：

```js
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '../views/HomeView.vue'

const routes = [{ path: '/', component: HomeView }]

export default createRouter({
  history: createWebHistory(),
  routes,
})
```

📌 `HomeView.vue` 可放簡單的 `<template><h1>Home</h1></template>` 當作測試畫面。

---

## ⚙️ 三、主程式 main.js 組裝流程

📌 來源整合：〈總覽〉 + 〈指南〉

在 Vue 專案中，`main.js` 是整個應用的啟動點，它會負責：

1. 建立 Vue App 實體
2. 掛載 UI 套件（如 PrimeVue）
3. 掛載插件（如 Pinia、Router）
4. 匯入全域樣式與資源
5. 把應用掛載到 `index.html` 的 `#app` 上

---

### 📂 `main.js` 最基本範例

```js
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.mount('#app')
```

這段程式是 Vue 的最小啟動形式。

---

### 💡 專案中實際常見的完整版本（整合 Pinia、PrimeVue、Router）

```js
import { createApp } from 'vue'
import App from './App.vue'

// 🌟 PrimeVue UI 套件與樣式
import PrimeVue from 'primevue/config'
import 'primevue/resources/themes/lara-light-blue/theme.css' // 主題樣式
import 'primevue/resources/primevue.min.css'                 // 元件樣式
import 'primeicons/primeicons.css'                           // 圖示樣式
import 'primeflex/primeflex.css'                             // 排版工具（選用）

// 🧠 狀態管理
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

// 🚦 Router（使用 vue-router）
import router from './router' // 或自動路由請看下一節

const app = createApp(App)

// 📌 掛載插件與元件
app.use(PrimeVue)

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
app.use(pinia)

app.use(router)
app.mount('#app')
```

---

### 🧠 每個步驟解釋

| 匯入項目                      | 用途說明                                             |
| ------------------------- | ------------------------------------------------ |
| `PrimeVue` + 樣式           | 設定 PrimeVue UI 套件、載入主題與基本樣式、圖示庫與排版工具             |
| `createPinia()` + persist | 啟用狀態管理與資料持久化（登入、token、購物車等常見場景）                  |
| `router`                  | 註冊前端路由控制，讓 `<router-view>` 可以正確切換畫面              |
| `.mount('#app')`          | 把整個 App 掛載到 `index.html` 中的 `<div id="app">` 元素上 |

---

### 📦 PrimeVue 元件註冊提醒

PrimeVue 不會自動讓元件可以用，建議你用「集中註冊」方式管理：

```js
// plugins/primevue.js
import Button from 'primevue/button'
import Dialog from 'primevue/dialog'

export default (app) => {
  app.component('Button', Button)
  app.component('Dialog', Dialog)
}
```

然後在 `main.js` 使用：

```js
import registerPrimeVue from './plugins/primevue'
registerPrimeVue(app)
```

這樣一來，不只可讀性高，也方便統一管理與更新元件。

---

## 🗂 四、資料夾結構與命名建議

📌 來源整合：〈總覽〉 + 〈指南〉
🎯 目的：幫助你建立一套「好讀好維護的專案資料夾結構」

---

### 🏗 推薦的 Vue 專案資料夾結構總覽

```
📁 src/
├── assets/        # 靜態圖像與樣式（圖片、音效、字型等）
├── styles/        # 全域樣式（SCSS、變數、reset）
├── components/    # 可重用 UI 元件（按鈕、彈窗、欄位）
├── views/         # 頁面元件（對應路由畫面，通常搭配 router）
├── layouts/       # 畫面版型（default.vue, admin.vue 等）
├── router/        # Vue Router 設定（若使用手動路由）
├── store/         # 狀態管理（pinia 資料夾，可替代為 `pinia/`）
├── plugins/       # 插件初始化（PrimeVue, i18n, VeeValidate 等）
├── composables/   # 自定義 `useXXX()` 工具函式
├── services/      # axios API 請求封裝（如 userService.js）
├── constants/     # 靜態資料、對照表、表單選項等
├── utils/         # 純邏輯工具函式（非 Vue，資料轉換/運算邏輯等）
├── App.vue        # 主元件（整個應用畫面的容器）
└── main.js        # Vue 應用啟動點
```

---

### 📚 每個資料夾用途說明表格

| 資料夾名稱          | 📦 職責    | 🔍 說明與常見內容                                              |
| -------------- | -------- | ------------------------------------------------------- |
| `assets/`      | 靜態資源區    | 圖片、影片、音效、字型，能直接用於 `<img src>`                           |
| `styles/`      | 全域樣式設定   | SCSS 主題變數、reset.css、共用樣式模組                              |
| `components/`  | 可重用元件    | 小型 UI 元件：按鈕、Modal、表單欄位等，使用 `props`/`slots` 提高彈性         |
| `pages/`       | 頁面元件     | 路由對應畫面元件，每個頁面一個 `.vue`                                  |
| `layouts/`     | 頁面版型     | 用於 `vite-plugin-vue-layouts-next`，設定 default/admin 畫面框架 |
| `router/`      | 前端路由設定   | 若使用手動路由，在這裡管理 `index.js` 等                              |
| `store/`       | 全域狀態管理   | 使用 Pinia 管理如登入資訊、購物車、Token 等                            |
| `plugins/`     | 插件初始化    | 用於集中註冊 PrimeVue、VeeValidate 等，讓 main.js 更乾淨             |
| `composables/` | 自定義邏輯工具  | 自製 `useXXX()` 函式，強化 Composition API 模組化                 |
| `services/`    | API 請求封裝 | 放各種後端 API 封裝，例如 `userService.js`、`orderService.js`      |
| `constants/`   | 常數定義資料   | 狀態對照表、表單選項、錯誤代碼等                                        |
| `utils/`       | 純邏輯函式    | 非 Vue 專用邏輯，例如格式轉換、數字計算、驗證工具等                            |

---

### 🧭 建立時機與命名小提醒

| 建立時機           | 建議                     |
| -------------- | ---------------------- |
| `.env`         | 有 API 時立即建立            |
| `router/`      | 安裝 `vue-router` 後      |
| `store/`       | 有登入/購物車/共用資料需求時建立      |
| `services/`    | 有任何 API 請求前就該建立        |
| `plugins/`     | 安裝 Vue Plugin 就應建立初始化檔 |
| `composables/` | 需要跨元件共用的功能邏輯時建立        |

---

### 📦 命名慣例整理

| 概念項目          | 建議命名                      | 補充說明                                    |
| ------------- | ------------------------- | --------------------------------------- |
| API 請求封裝區     | `services/`               | 命名如 `userService.js`，可集中維護路徑與邏輯         |
| 狀態管理資料夾       | `store/`                  | 也可用 `pinia/`，選一種固定全專案一致即可               |
| 工具函式區         | `utils/`                  | 命名如 `formatDate.js`, `calculateWeek.js` |
| 靜態常數對照表區      | `constants/`              | 命名如 `statusMap.js`, `formOptions.js`    |
| 可重用元件 vs 頁面元件 | `components/` vs `views/` | 前者為積木模組，後者為對外整頁畫面                       |

---

## 📦 五、開發套件說明與使用技巧

📌 來源整合：〈總覽〉 + 〈指南〉
🎯 本章會依功能分類整理所有重要開發套件，幫助你理解每個套件的用途、安裝方式與搭配使用技巧。

---

### 🧰 類別一：Vue 基礎輔助工具

| 套件名稱                  | 功能說明                                                                              |
| --------------------- | --------------------------------------------------------------------------------- |
| `@vueuse/core`        | Vue 的實用工具函式庫，提供許多 `useXXX()` 開頭的 Composition API 函式（如：`useMouse()`、`useDark()` 等） |
| `vite-plugin-inspect` | 查看 Vite 插件運作情況（瀏覽 `/__inspect` 頁面可除錯）                                             |

📦 安裝指令：

```bash
npm i @vueuse/core
npm i -D vite-plugin-inspect
```

---

### 🔍 類別二：語法風格與格式工具（ESLint + Prettier）

| 套件                       | 功能說明                            |
| ------------------------ | ------------------------------- |
| `eslint`                 | 檢查程式語法、邏輯錯誤                     |
| `prettier`               | 統一排版格式（如縮排、分號、引號等）              |
| `eslint-plugin-prettier` | 讓 Prettier 整合進 ESLint 流程        |
| `eslint-config-prettier` | 關掉 ESLint 跟 Prettier 重疊的規則，避免衝突 |
| `eslint-plugin-vue`      | 專門針對 `.vue` 檔的 ESLint 規則檢查      |

📦 安裝指令：

```bash
npm init @eslint/config@latest
npm i -D eslint prettier eslint-plugin-prettier eslint-config-prettier eslint-plugin-vue
```

📄 ESLint 設定範例：`eslint.config.js`
📄 Prettier 設定範例：`.prettierrc.json`
（見前面內容已完整提供）

---

### 🎨 類別三：UI 套件整合（PrimeVue）

| 套件名稱         | 功能說明                                       |
| ------------ | ------------------------------------------ |
| `primevue`   | 提供各種內建 UI 元件，如 `<Button>`、`<Dialog>` 等     |
| `primeicons` | 圖示庫，可透過 `<i class="pi pi-check"></i>` 使用   |
| `primeflex`  | 類似 Tailwind 的工具類別排版系統（`.flex`, `.gap-2` 等） |

📦 安裝指令：

```bash
npm i primevue@latest primeicons primeflex
```

📂 在 `main.js` 中匯入對應樣式與 `.use(PrimeVue)` 即可使用。

🧠 小提醒：元件需手動註冊，可集中寫在 `plugins/primevue.js` 統一管理。

---

### 🧠 類別四：狀態管理（Pinia）

| 套件名稱                          | 功能說明                               |
| ----------------------------- | ---------------------------------- |
| `pinia`                       | Vue 官方推薦的狀態管理（取代 Vuex）             |
| `pinia-plugin-persistedstate` | 將狀態儲存在 localStorage，支援登入紀錄、跨頁狀態保存等 |

📦 安裝指令：

```bash
npm i pinia pinia-plugin-persistedstate
```

📄 在 `main.js` 中：

```js
const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
app.use(pinia)
```

---

### 🔌 類別五：後端互動與 API 封裝

| 套件名稱     | 功能說明                               |
| -------- | ---------------------------------- |
| `axios`  | 發送 HTTP 請求（`GET`, `POST`, `PUT` 等） |
| `dotenv` | 讀取 `.env` 環境變數（後端 Express 用）       |

📦 安裝指令：

```bash
npm i axios
npm i express dotenv  # 若需要後端
```

🧠 建議搭配 `services/xxxService.js` 分工封裝，並使用 `try/catch` 處理錯誤。

---

### ✅ 類別六：表單驗證與資料格式處理（僅《總覽》有提及）

| 套件名稱                   | 功能說明                                   |
| ---------------------- | -------------------------------------- |
| `vee-validate` + `yup` | 表單驗證組合：`yup` 定義 schema，`vee` 整合 Vue UI |
| `dayjs`                | 輕量版 `moment.js`，格式轉換、相對時間處理            |
| `@iconify/vue`         | 萬用圖示庫，可支援超過百種 icon 集合                  |

📦 安裝指令（整包）：

```bash
npm i pinia pinia-plugin-persistedstate axios vee-validate yup dayjs @iconify/vue
```

---

## 🔧 六、進階功能與懶人工具 × 動畫互動補充

📌 來源整合：〈指南〉 + 〈總覽〉

這些工具不是啟動專案的「必裝項」，但一旦畫面與檔案增加，就能大幅 **降低手動 import、元件註冊、路由設定、layout 切換** 的重複工作；另外，動畫與輪播套件讓畫面更有互動感。

---

### 6-1 懶人工具四件組（Auto Import / Components / Router / Layouts）

| 目標            | 套件                             | 作用                                 |
| ------------- | ------------------------------ | ---------------------------------- |
| 自動引入函式        | `unplugin-auto-import`         | 不用再手寫 `import { ref } from 'vue'`  |
| 自動註冊元件        | `unplugin-vue-components`      | `/components`、PrimeVue 元件自動可用      |
| 自動產生路由        | `unplugin-vue-router`          | 掃描 `/src/pages` → 生成路由表            |
| 自動套用頁面 Layout | `vite-plugin-vue-layouts-next` | 每個頁面用 `definePageMeta()` 指定 layout |

📦 一口氣安裝：

```bash
npm i -D unplugin-auto-import unplugin-vue-components unplugin-vue-router vite-plugin-vue-layouts-next
```

#### Vite 設定範例（精簡版）

```js
import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import AutoImport     from 'unplugin-auto-import/vite'
import Components     from 'unplugin-vue-components/vite'
import { PrimeVueResolver } from 'unplugin-vue-components/resolvers'
import VueRouter      from 'unplugin-vue-router/vite'
import Layouts        from 'vite-plugin-vue-layouts-next'
import { VueRouterAutoImports } from 'unplugin-vue-router'

export default defineConfig({
  plugins: [
    VueRouter(),               // ① 自動路由
    Layouts(),                 // ② 自動 layout
    Vue(),                     // ③ 解析 .vue 檔
    Components({               // ④ 自動元件
      resolvers: [PrimeVueResolver()],
    }),
    AutoImport({               // ⑤ 自動 import
      imports: [
        'vue',
        VueRouterAutoImports,  // 把 router 方法也自動引入
        { pinia: ['defineStore', 'storeToRefs'] },
      ],
      vueTemplate: true,
      eslintrc: { enabled: true },
    }),
  ],
})
```

> ✅ 只要 `/src/pages/about.vue` 存在，就會自動得到路由 `/about`；
> ✅ `<Button>` 放在任意 `.vue`，插件會自動幫你 `import` 並註冊 PrimeVue 的 Button；

---

### 6-2 PrimeVue × Layouts × Router 實際配合流程

1. 在 `/src/layouts/` 建立 `default.vue`, `admin.vue`, `auth.vue` …
2. 在頁面元件 `<script setup>` 中加入：

   ```vue
   definePageMeta({ layout: 'admin' })
   ```
3. `vite-plugin-vue-layouts-next` 會自動包裝對應 layout。

---

### 6-3 字體套件 - `unplugin-fonts`

> Google Fonts 自動下載打包，避免 FOUC

```bash
npm i -D unplugin-fonts
```

在 `vite.config.js`：

```js
import Fonts from 'unplugin-fonts/vite'
Fonts({
  google: { families: [{ name: 'Roboto', styles: 'wght@100;300;400;700' }] },
})
```

---

### 6-4 動畫／互動功能套件（來自〈總覽〉）

| 套件           | 分類     | 用途亮點                   | 適合情境             |
| ------------ | ------ | ---------------------- | ---------------- |
| **GSAP**     | 動畫函式庫  | 功能最完整、效能佳、控制精細         | 頁面轉場、滾動觸發動畫、流程動畫 |
| **Swiper**   | 輪播工具   | loop / autoplay，行動裝置友善 | Banner、產品圖輪播     |
| **Anime.js** | 輕量動畫工具 | 語法簡單，入門快速              | Icon 漂浮、數字遞增動畫   |

使用提醒：

```vue
<script setup>
import { Swiper, SwiperSlide } from 'swiper/vue'
import 'swiper/css'
import gsap from 'gsap'
import { onMounted } from 'vue'

onMounted(() => {
  gsap.to('.box', { x: 300, duration: 1 })
})
</script>
```

> *GSAP / Anime.js* 需等元件掛載完成再操作 DOM，建議寫在 `onMounted`。
> *Swiper* 記得引入 `/css`，並建議用 `swiper/vue` 元件版本。

---

## 🧩 七、axios × Proxy × Express 串接整合實戰

📌 來源：〈總覽〉為主，補充整合《指南》簡版內容
🎯 教你從前端打 API → 經過 Proxy 轉發 → 到後端 Express 回傳資料的完整流程

---

### 📦 7-1 問題背景：CORS 跨域錯誤是怎麼發生的？

假設：

* Vue（Vite）跑在：`http://localhost:5173`
* Express 跑在：`http://localhost:3000`

你在前端這樣寫：

```js
axios.get('http://localhost:3000/api/hello')
```

🚨 會出現錯誤：

```
❌ Access to fetch at 'http://localhost:3000/api/hello' 
from origin 'http://localhost:5173' has been blocked by CORS policy
```

---

### ✅ 7-2 解法：使用 Vite Proxy 轉發 API

#### 📌 改寫 axios 請求（只寫 `/api/...`）

```js
axios.get('/api/hello')
```

#### 📌 在 `vite.config.js` 加入 proxy 設定

```js
server: {
  proxy: {
    '/api': 'http://localhost:3000'
  }
}
```

這表示：

> 「前端發送 `/api/xxx`，Vite 幫你偷偷轉送到 `http://localhost:3000/api/xxx`」

✅ 避開跨域限制（CORS），前端不用知道後端在哪。

---

### 🛠 7-3 Express 後端 API 範例（含 `.env`）

📁 `server/index.js`

```js
import express from 'express'
import dotenv from 'dotenv'
dotenv.config()

const app = express()
const port = process.env.PORT || 3000

app.get('/api/hello', (req, res) => {
  res.json({ message: 'Hello from backend!' })
})

app.listen(port, () => {
  console.log(`✅ Server running at http://localhost:${port}`)
})
```

📁 `.env`

```env
PORT=3000
VITE_API_BASE_URL=http://localhost:3000
```

---

### 🔁 7-4 在前端使用 `.env` + axios

📁 `.env`：

```env
VITE_API_BASE_URL=http://localhost:3000
```

📁 `services/userService.js`：

```js
import axios from 'axios'

const baseURL = import.meta.env.VITE_API_BASE_URL

export const login = (formData) => axios.post(`${baseURL}/login`, formData)
export const fetchUser = (id) => axios.get(`${baseURL}/user/${id}`)
```

---

### ☂️ 7-5 加入 try/catch 與錯誤處理

```js
export const fetchUser = async (id) => {
  try {
    const res = await axios.get(`${baseURL}/user/${id}`)
    return res.data
  } catch (error) {
    console.error('❌ 無法取得使用者資料', error)
    throw error
  }
}
```

---

### 🛡️ 7-6 建立 axiosInstance（進階）

📁 `services/axiosInstance.js`

```js
import axios from 'axios'

const instance = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
})

// 自動附加 Token
instance.interceptors.request.use((config) => {
  const token = localStorage.getItem('token')
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

export default instance
```

之後就能改為這樣用：

```js
import api from './axiosInstance'

export const fetchUser = (id) => api.get(`/user/${id}`)
```

---

### 🧭 7-7 多環境 Proxy 寫法

```js
const isDev = process.env.NODE_ENV === 'development'

server: {
  proxy: {
    '/api': isDev
      ? 'http://localhost:3000'
      : 'https://your-prod-api.com'
  }
}
```

---

✅ 到這裡，你的前後端開發流程就能：

```
Vue 組件 → axios 發送 /api → Vite Proxy → Express 後端回應 JSON → 畫面更新
```

---

## 📚 八、結構補遺 × 建立時機 × 三方分工整理

📌 來源：〈總覽〉補充區段
🎯 整理零散但實用的概念與規則，方便查表與回顧

---

### 🧱 8-1 各資料夾「建立時機」與啟用條件

| 資料夾 / 功能區      | 建立時機 or 什麼情況需要？                             | 備註                          |
| -------------- | ------------------------------------------- | --------------------------- |
| `router/`      | 安裝 `vue-router` 後（無論是手動還是自動路由）              | 建立 `index.js` 並定義 routes    |
| `views/`       | 一開始就需要，對應每個路由畫面                             | 每個畫面一個 .vue                 |
| `components/`  | 實作畫面時會自然需要（按鈕、表單、卡片等）                       | 建議分類 + 對應 props/slots       |
| `plugins/`     | 安裝任何 Plugin 後（如 PrimeVue, VeeValidate）      | 把初始化邏輯集中收納                  |
| `store/`       | 有跨元件 / 跨頁共用資料時（登入狀態、購物車等）                   | Pinia + plugin 註冊           |
| `services/`    | 只要開始呼叫 API，就應建立                             | 每個功能模組一個 .js                |
| `composables/` | 出現多次共用邏輯時（如 useForm、useAuth、useQueryString） | 自定義 useXXX 函式區              |
| `constants/`   | 有固定選項、對照資料、狀態碼等時（如 select 選單）               | 與邏輯分離，方便維護                  |
| `.env`         | 有 baseURL、PORT、API key 等變數需求時               | `VITE_` 為前端變數前綴             |
| `.gitignore`   | 開專案第一天就該建立                                  | 避免上傳 node\_modules / .env 等 |

---

### 🧠 8-2 `views/` vs `components/` 差異表

| 比較項目 | `views/`                  | `components/`                       |
| ---- | ------------------------- | ----------------------------------- |
| 定位   | 路由對應的整頁畫面                 | 可重用 UI 小模組                          |
| 用途   | `router-view` 顯示畫面        | 組合式拼圖，例如按鈕、欄位、Modal 等               |
| 出現頻率 | 一個頁面一個                    | 可多頁共用                               |
| 對應路徑 | 通常 `/src/views/PageX.vue` | 通常 `/src/components/ComponentX.vue` |

---

### 🎯 8-3 Vue × Vite × PrimeVue 三方分工表

| 功能語法                                     | 誰決定的？      | 功能說明或設計邏輯                        |
| ---------------------------------------- | ---------- | -------------------------------- |
| `createApp(App)`                         | Vue        | Vue 應用的啟動方式                      |
| `.mount('#app')`                         | Vue        | 掛載 Vue 應用至 HTML 畫面               |
| `import App.vue`                         | Vue + Vite | Vite 支援 `.vue` 檔案模組解析            |
| `import PrimeVue from 'primevue/config'` | PrimeVue   | UI 套件初始化（需 `.use()` 註冊）          |
| `import 'primevue/resources/...`         | PrimeVue   | 樣式需手動引入才能生效（主題樣式、元件樣式、icon、排版工具） |
| `import.meta.env.VITE_API_BASE_URL`      | Vite       | 前端讀取 `.env` 需加 `VITE_` 開頭        |
| `vite.config.js` 中的 `plugins`            | Vite       | 所有插件整合的設定區，控制路由、元件註冊、自動 import 等 |

---

### 📘 8-4 小知識補充區

* 📂 Git 不會追蹤空資料夾，需放一個 `.gitkeep` 讓它保留結構
* 🔐 `.env` 不應上傳到 Git，因為通常包含敏感資訊
* 🔁 多環境 `.env.production` / `.env.development` Vite 會自動切換
* ⚙️ `defineConfig()` 是 Vite 的設定統一入口（對等於 webpack.config）

---

## 🧰 九、常駐功能型工具 × 專案中期常用套件

📌 來源：《總覽》功能分類區段

這些工具雖不是「初始化專案」就必裝，但只要專案一進入登入系統 / 資料傳輸 / 表單驗證等階段，幾乎都會出現，建議在「專案中期」評估導入。

---

### 🧱 9-1 常駐型功能工具六件組

| 套件名稱                          | 類型      | 適合使用時機                | 簡要說明                                 |
| ----------------------------- | ------- | --------------------- | ------------------------------------ |
| `pinia`                       | 狀態管理    | 有登入資訊 / 多頁共用資料需求時     | Vue 官方推薦的狀態管理工具，取代 Vuex              |
| `pinia-plugin-persistedstate` | 狀態儲存    | 登入狀態須保留（刷新不消失）時       | 可自動儲存到 localStorage 或 sessionStorage |
| `axios`                       | HTTP 請求 | 只要要打 API 就需要          | 處理資料傳輸，配合 Vite Proxy 可避開 CORS        |
| `vee-validate` + `yup`        | 表單驗證    | 有表單送出行為時（註冊、登入、填寫資料等） | `vee` 綁定欄位與規則、`yup` 設計規則架構           |
| `dayjs`                       | 時間處理    | 需要顯示、運算、轉換日期時間時       | 輕量化的 moment.js 替代品                   |
| `@iconify/vue`                | Icon 套件 | 有自訂 icon 或大量 icon 使用時 | 支援萬國圖示庫，可自由指定 icon name 使用           |

---

### 🛠 9-2 安裝範例與使用技巧

#### ✅ `pinia` × `persistedstate` 安裝與註冊

```bash
npm i pinia
npm i pinia-plugin-persistedstate
```

📁 `main.js` 註冊：

```js
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

app.use(pinia)
```

📁 `store/user.js`：

```js
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({ token: '', userData: {} }),
  persist: true
})
```

---

#### ✅ `vee-validate` × `yup` 表單驗證

```bash
npm i vee-validate yup
```

📁 `components/LoginForm.vue`：

```vue
<script setup>
import { useForm, useField } from 'vee-validate'
import * as yup from 'yup'

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().min(6).required()
})

const { handleSubmit } = useForm({ validationSchema: schema })
const { value: email } = useField('email')
const { value: password } = useField('password')

const onSubmit = handleSubmit(values => {
  console.log('✅ 資料正確送出', values)
})
</script>
```

---

#### ✅ `@iconify/vue` 安裝與使用

```bash
npm i @iconify/vue
```

```vue
<script setup>
import { Icon } from '@iconify/vue'
</script>

<template>
  <Icon icon="mdi:home" />
</template>
```

> 查找 icon name 請至：[https://icones.js.org/](https://icones.js.org/)

---

#### ✅ `dayjs` 常用範例

```bash
npm i dayjs
```

```js
import dayjs from 'dayjs'

console.log(dayjs().format('YYYY-MM-DD'))
console.log(dayjs('2025-07-09').fromNow())
```

---

### 📘 9-3 小結

* **pinia + persist** 處理登入資訊與跨頁共用狀態
* **axios** 處理 API 串接、可配合 token 注入
* **vee + yup** 為驗證表單提供強大支援
* **dayjs** 操作時間超直覺
* **iconify** 萬用 icon 套件，不再被框在特定 UI 套件中

---

## 🎞️ 十、動畫與展示強化工具總覽

📌 來源：〈總覽〉功能工具補充區
🎯 畫面動態、過場動畫、輪播展示等互動功能，需仰賴額外 UI 工具或動畫函式庫支援。這些套件常見於 Landing Page、行銷頁、圖文輪播區等。

---

### 🎬 10-1 三大動畫函式庫與用途對照

| 套件名稱       | 適合使用時機                 | 特性簡介               |
| ---------- | ---------------------- | ------------------ |
| `gsap`     | 時間軸動畫、進場特效、滾動動畫等       | 極強大動畫控制函式庫，可製作精緻動畫 |
| `anime.js` | 精緻 SVG / Canvas 動畫     | 精準控制動畫屬性，可做細節微動畫   |
| `AOS`      | 卷軸動畫（scroll reveal 效果） | 畫面滑入滑出動畫的懶人套件，效果簡潔 |

---

### 🎠 10-2 三大圖文輪播工具比較

| 套件名稱            | 使用場景      | 特性或優缺點備註                     |
| --------------- | --------- | ---------------------------- |
| `swiper`        | 輪播圖、卡片滑動區 | 功能完整、社群活躍，支援觸控滑動，設計彈性高       |
| `vue3-carousel` | 簡單輪播需求    | 輕量好用，語法簡單，適合初學者              |
| `splide`        | 特殊輪播效果    | 支援 vertical slide、fade 等多種模式 |

> 📌 若已使用 PrimeVue，內建 `Carousel` 元件也可用來展示清單型圖片卡片。

---

### ⚙️ 10-3 安裝與基本使用範例（以 `swiper` 為例）

```bash
npm i swiper
```

📁 `components/ImageSwiper.vue`：

```vue
<script setup>
import { Swiper, SwiperSlide } from 'swiper/vue'
import 'swiper/css'
</script>

<template>
  <Swiper :slides-per-view="1" loop autoplay>
    <SwiperSlide v-for="i in 3" :key="i">
      <img :src="`/img/banner-${i}.jpg`" />
    </SwiperSlide>
  </Swiper>
</template>
```

---

### 🎯 10-4 元件設計搭配建議

* ✨ 如果追求 **動畫精緻度、流程控制**：用 `gsap` + 時間軸
* 🌀 如果希望 **快速套用卷軸出現效果**：用 `AOS` + class 套件
* 📷 如果需要 **展示圖片／滑動卡片區塊**：用 `swiper` 或內建 `Carousel`

---

### 🧩 10-5 實務小撇步

* 動畫請酌量使用，不建議所有元件都加動畫 → 容易疲勞＋效能負擔
* 多數動畫函式庫不會主動移除效果，切換頁面記得清除 / dispose
* 若使用 `keep-alive`，動畫效果與 hook 行為可能出現異常，需注意設計順序

---

## 🗂 十一、Vue 專案骨架 × 資料夾職責地圖

📌 來源：《總覽》中段「專案目錄與邏輯結構總覽」段落
🎯 幫助你快速掌握每個資料夾的作用、建立時機、典型內容與命名慣例

---

### 📂 11-1 Vue × Vite 專案資料夾一覽圖（文字化版本）

```
📦 /src
├── 📁 assets         → 靜態圖片、圖示、icon（非 components 圖示）
├── 📁 components     → 可重複元件（按鈕、欄位、彈窗、卡片）
├── 📁 views          → 路由對應畫面（每頁一個）
├── 📁 layouts        → 導覽列、頁面框架、Layout 組合結構
├── 📁 router         → 路由設定（Vue Router）＋ routes 對應表
├── 📁 store          → pinia 狀態管理（登入資訊、跨頁資料）
├── 📁 plugins        → 各類 Plugin 初始化與註冊（如 PrimeVue、axios）
├── 📁 services       → API 封裝與資料存取邏輯（axios + baseURL）
├── 📁 composables    → 共用邏輯（useXXX），與元件無關的邏輯模組
├── 📁 styles         → SCSS 或全域樣式檔（含 Reset、變數、佈局等）
├── 📁 constants      → 常數對照表、狀態碼、下拉選單選項等固定資料
├── 📁 data           → 假資料 / 測試資料（不進行 fetch）
├── 📁 directives     → 自定義 Vue 指令（v-focus, v-intersect 等）
├── 📄 main.js        → 程式主入口：App 啟動、Plugin 註冊等
├── 📄 App.vue        → App 框架主元件（通常只放 router-view）
```

---

### 🧭 11-2 資料夾職責 × 功能分工一覽表

| 資料夾名稱          | 職責定位             | 典型內容與建議                           | 建立時機            |
| -------------- | ---------------- | --------------------------------- | --------------- |
| `views/`       | 路由對應畫面（每頁一個）     | PageA.vue、PageB.vue               | 安裝 Vue Router 後 |
| `components/`  | 共用元件區，重複使用的 UI   | InputField.vue、Modal.vue          | 開始畫面開發時         |
| `layouts/`     | Layout 樣板，提供頁面骨架 | DefaultLayout.vue、AdminLayout.vue | 頁面區分明顯或有固定框架時   |
| `router/`      | 路由總表與 route 模組   | index.js、routes 資料夾               | 安裝 Vue Router 後 |
| `store/`       | 狀態儲存與共用資料        | user.js、cart.js、auth.js           | 有登入或跨頁資料需求時     |
| `services/`    | API 操作封裝（axios）  | userService.js、orderService.js    | 要串接後端 API 時     |
| `composables/` | 共用邏輯（自定義 Hook）   | useForm.js、useAuth.js             | 多次重複的邏輯出現時      |
| `plugins/`     | 插件初始化設定          | veeValidate.js、primevue.js        | 安裝任何 Plugin 套件後 |
| `constants/`   | 常數表 / 對照資料       | statusMap.js、dropdownOptions.js   | 下拉選單、狀態碼出現時     |
| `styles/`      | 樣式相關             | base.scss、reset.css、theme.css     | 使用 SCSS 或設計系統時  |
| `data/`        | 模擬資料（非 fetch）    | mockUser.json、staticTable.js      | 尚無後端資料、先行測試用    |
| `directives/`  | 自定義指令            | v-focus.js、v-intersect.js         | 有特殊 DOM 行為需求時   |

---

### 🧠 11-3 補充觀念 × 建議命名策略

* ✅ 檔案名建議使用 **小駝峰** 或 **首字大寫** 規則（如：`LoginPage.vue` / `userService.js`）
* ✅ 資料夾內若超過 5 個以上 .vue/.js 建議分子資料夾（by 主題 or by 模組）
* ✅ 可以加 `.gitkeep` 保留空資料夾結構，避免被 Git 忽略

---

### 📌 小提醒：不要亂混分類！

| 錯誤例子               | 改進方式                          |
| ------------------ | ----------------------------- |
| 把 API 寫在元件內        | 拆出去放在 `services/`             |
| 把登入狀態寫在 props 傳來傳去 | 使用 `pinia` 或 inject / provide |
| 把 layout 跟頁面綁在一起   | 抽出 layout 檔案，讓 views 更乾淨      |
| 所有東西都寫一頁沒拆開        | 模組化各功能，維持可維護性與可讀性             |

---

## 📄 附錄：`main.js` 流程逐行說明 × 啟動邏輯全解

📌 來源：《總覽》最尾段補充
🎯 幫助你理解 Vue + Vite 專案從 `main.js` 啟動時，實際發生了什麼事，哪些是必要的、哪些是套件設定。

---

### 🪜 啟動流程概觀（初始化順序）

1. 匯入 Vue 套件與 App 主元件
2. 建立應用程式實體
3. 註冊各種 Plugin（如 Pinia、Router、PrimeVue）
4. 掛載到 HTML 頁面

---

### 🔍 每行說明範例

📁 `main.js`（典型格式）：

```js
import { createApp } from 'vue'                  // 匯入 Vue 主功能
import App from './App.vue'                      // 匯入整個應用的最外層元件
import router from './router'                    // 匯入路由設定
import PrimeVue from 'primevue/config'           // 引入 UI 套件
import { createPinia } from 'pinia'              // 狀態管理工具
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'  // 狀態儲存插件

import './styles/main.scss'                      // 匯入全域樣式
import 'primevue/resources/themes/aura-light-green/theme.css'  // 主題樣式
import 'primeicons/primeicons.css'               // PrimeVue 專用圖示
import 'primevue/resources/primevue.min.css'      // PrimeVue 核心樣式

const app = createApp(App)                       // 建立 Vue 應用
const pinia = createPinia()                      // 建立 Pinia 實體
pinia.use(piniaPluginPersistedstate)             // 注入 plugin 功能

app.use(router)                                  // 掛載 Vue Router
app.use(pinia)                                   // 掛載 Pinia
app.use(PrimeVue)                                // 掛載 PrimeVue（還可設定 config）

app.mount('#app')                                // 掛載到 HTML 中的 <div id="app">
```

---

### 🧠 延伸知識補充

| 對象                     | 功能說明與使用時機                              |
| ---------------------- | -------------------------------------- |
| `createApp(App)`       | 建立 Vue 應用的入口點，是一切邏輯的起點                 |
| `app.use(...)`         | 注入各種外部功能，如路由、UI 套件、狀態管理等               |
| `app.mount('#app')`    | 將 Vue 接手渲染控制 `<div id="app">` 中的內容     |
| `App.vue`              | 整個畫面的最外層元件，通常只有 layout 與 `router-view` |
| `import './styles/...` | 所有樣式檔案與資源（SCSS、icon、外部主題）需明確載入         |

---

### ⚠️ 常見錯誤與除錯提醒

| 問題訊息                                  | 常見原因                             |
| ------------------------------------- | -------------------------------- |
| `Cannot read properties of undefined` | Plugin 使用順序錯誤，或未 `.use()`        |
| 畫面無樣式                                 | 忘記引入 PrimeVue 主題 / 核心 CSS        |
| 路由跳轉無效                                | 忘記 `app.use(router)` 或路由檔案路徑錯誤   |
| 頁面刷新狀態消失                              | 忘記使用 `piniaPluginPersistedstate` |

---

### ✅ 小結與實務建議

* 建議將 `main.js` 統一作為初始化中心，不要把 Plugin 直接放在其他地方引入，便於管理與閱讀
* 若邏輯複雜，可拆分為：`main.js` + `plugins/index.js` 統整 Plugin 註冊
* 若有多組樣式檔，可集中在 `/styles/main.scss` 統一引入，避免漏掉

---

## 🧩 十二、進階設定 × 問題排解 × 套件工具包

📌 來源：《總覽》遺漏補遺 × 輔助工具與除錯技巧
🎯 整合常見的設定技巧、開發過程中好用的輔助工具、以及報錯排解小抄，幫助你在實務開發中更穩定地前進。

---

### 🌐 12-1 Proxy 跨域設定 × API 重導技巧

📦 用途：避免 `CORS` 錯誤，前端模擬請求真實後端 API。

```js
// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'https://your-backend-server.com',
        changeOrigin: true,
        rewrite: path => path.replace(/^\/api/, '')
      }
    }
  }
})
```

| 設定項            | 說明                                |
| -------------- | --------------------------------- |
| `target`       | 你要導向的真實 API 網址                    |
| `changeOrigin` | 是否修改來源標頭為目標主機（預設為 false）          |
| `rewrite`      | 重寫路徑：將 `/api/xxx` 改成 `/xxx` 發送到後端 |

> ⚠️ 若未設定 rewrite，後端若不接受 `/api` 前綴可能會出錯。

---

### 🛠 12-2 開發輔助插件清單 × 自動化工具

| 套件名稱                      | 功能                                        | 安裝方式                               |
| ------------------------- | ----------------------------------------- | ---------------------------------- |
| `unplugin-auto-import`    | 自動導入常用函式（如 `ref`, `computed`）             | `npm i -D unplugin-auto-import`    |
| `unplugin-vue-components` | 自動註冊元件                                    | `npm i -D unplugin-vue-components` |
| `unplugin-vue-router`     | 自動掃描 pages，生成 routes                      | `npm i -D unplugin-vue-router`     |
| `vite-plugin-pages`       | 對應資料夾自動生成頁面路由                             | `npm i -D vite-plugin-pages`       |
| `vite-plugin-inspect`     | Vite 插件可視化（開 `localhost:5173/__inspect/`） | `npm i -D vite-plugin-inspect`     |

🔧 使用這些插件能省下許多樣板程式碼，減少錯誤與重複工作，建議在中型以上專案就導入。

---

### 🎨 12-3 PrimeVue 樣式設定 × 主題選擇小技巧

```js
// main.js 範例
import 'primevue/resources/themes/aura-light-green/theme.css'
import 'primevue/resources/primevue.min.css'
import 'primeicons/primeicons.css'
```

| 樣式檔                | 功能說明                         |
| ------------------ | ---------------------------- |
| `theme.css`        | 主題樣式：需選擇一種（Aura 系列、Lara 系列等） |
| `primevue.min.css` | 核心樣式（按鈕、表單等通用 UI）            |
| `primeicons.css`   | Prime 專屬圖示字型                 |

✅ 主題選擇建議從 [官方主題列表](https://primevue.org/theming/#themes) 中挑選一套風格一致的來使用。

---

### 💻 12-4 VSCode 建議設定 × 開發效率加速器

| 工具 / 檔案                 | 說明與建議             |
| ----------------------- | ----------------- |
| `Volar`                 | Vue 官方推薦的語言支援擴充   |
| `Prettier`              | 統一程式碼格式           |
| `ESLint`                | 靜態程式碼檢查工具，找出潛在錯誤  |
| `.vscode/settings.json` | 可共用的團隊統一格式與快捷鍵設定檔 |

📁 `.vscode/settings.json` 範例：

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": ["javascript", "vue"]
}
```

---

### 🔍 12-5 安裝錯誤 × 執行錯誤對應小抄

| 錯誤訊息                                         | 原因與解法建議                       |
| -------------------------------------------- | ----------------------------- |
| `ERR_MODULE_NOT_FOUND`                       | 模組路徑錯誤，檔案名拼錯 / 忘了副檔名          |
| `Cannot read properties of undefined`        | 插件順序錯誤 / 資料未定義 / 初始化錯誤        |
| `vite not found` / `vite: command not found` | 忘記安裝 Vite（執行 `npm i vite -D`） |
| `SyntaxError: Unexpected token`              | 通常為語法錯誤，或 JSON 格式錯誤           |
| 畫面沒樣式                                        | 忘記引入主題 CSS 或順序錯誤              |

---

### 🧪 12-6 Node.js / npm 版本建議 × 環境建置

| 工具      | 推薦版本        | 說明                   |
| ------- | ----------- | -------------------- |
| Node.js | 18.x（LTS 版） | 穩定、安全、套件相容性高         |
| npm     | 9.x 或更新版本   | 與 Node.js 版本自動綁定     |
| nvm     | 最新版         | 多版本切換工具，推薦安裝開發多專案時使用 |

🧭 可使用命令確認版本：

```bash
node -v
npm -v
```

