Vue 3 + Vite + Pinia 前端開發完整指南
前言
在現代前端開發中，Vue 3、Vite 和 Pinia 已成為台灣及全球開發者的標準選擇。這三個工具組成了高效的開發工作流，從本地開發到生產部署。然而，許多新手對於這些工具的用途、開發流程，以及最後的部署方式存有誤解。本文將深入介紹這些工具的核心概念、實際應用流程，並詳細解答新手常見問題。
第一部分：核心工具介紹
什麼是 Vite？
Vite 是由 Vue 創造者尤雨溪開發的下一代前端構建工具。與傳統的 Webpack 相比，Vite 具有以下優勢：
核心特性
Vite 的開發伺服器在編譯時間上表現卓越，通常可在 260 毫秒內完成編譯。這是因為 Vite 採用了 ES 模組（ESM）的原生支持，無需預先打包所有代碼，而是在瀏覽器請求時即時編譯。相比之下，Webpack 需要預先構建整個應用，導致開發效率較低。
在生產環節中，Vite 使用 Rollup 作為底層打包器，生成高度優化的產物，包括最小化的 JavaScript、CSS，以及自動進行 Tree-shaking 以移除未使用的代碼。
Vite 支持的插件系統
Vite 提供了多個官方插件來增強開發體驗：
@vitejs/plugin-vue：解析 Vue 單文件組件（.vue 文件）@vitejs/plugin-vue-jsx：支持 JSX 語法開發複雜組件vite-plugin-vue-devtools：集成 Vue DevTools 調試工具unplugin-auto-import：自動導入常用 API，減少重複代碼
什麼是 Vue 3？
Vue 3 是現代前端框架，具備以下核心優勢：
- 響應式系統重寫：性能提升顯著
- Composition API：相比傳統 Options API，提供更靈活的代碼組織方式
- TypeScript 支持：完整的類型定義和 IDE 自動補全
- Fragment 特性：允許組件返回多個根元素
- Tree-shaking 友好：在構建時自動移除未使用代碼
什麼是 Pinia？
Pinia 是 Vue 3 的官方狀態管理庫，是 Vuex 的現代替代品。在 2022 年 2 月，Pinia 正式成為 Vue 生態系統的一部分，並成為 Vue 3 的推薦狀態管理方案。
Pinia 核心特點
Pinia 相比 Vuex 有多項改進：
| 特性 | Pinia | Vuex |
|---|---|---|
| 設計模式 | 模塊化（多個獨立 store） | 中央化（單一 store + 子模塊） |
| 代碼風格 | 簡潔直觀 | 冗長，需要更多樣板代碼 |
| API 易用性 | 函數式 API，無需記憶 “commit” 或 “dispatch” | 需要記住不同的操作名稱 |
| 文件大小 | 僅 1KB | 相對較大 |
| TypeScript 支持 | 完整支持，具備自動補全 | 支持但不如 Pinia |
Pinia 的模塊化設計意味著每個功能模塊可以擁有獨立的 store，而不是全部放在一個中央 store 中。這使得代碼更容易維護和擴展。
Pinia 的三個核心概念：
- State：應用的共享數據狀態
- Getters：類似計算屬性，用於派生狀態
- Actions：用於修改狀態的異步或同步操作
第二部分：開發工作流程
開發流程圖
text項目初始化 → 開發環境搭建 → 本地開發 → 測試 → 生產構建 → 部署
↓ ↓ ↓ ↓ ↓ ↓
npm create npm install npm run 單元測試 npm run 上傳至
vue@latest dev 測試 build web 伺服器
第一步：項目初始化
建立新的 Vue 3 + Vite 項目的最簡單方法是使用官方的 create-vue 工具：
bashnpm create vue@latest my-vue-app
在交互式提示中，你可以選擇所需的功能：
text✔ Add TypeScript? … Yes
✔ Add JSX Support? … Yes
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes
✔ Add Vitest for Unit Testing? … Yes
✔ Add an End-to-End Testing Solution? › Playwright
✔ Add ESLint for code quality? … Yes
✔ Add Prettier for code formatting? … Yes
這將自動生成完整的項目結構，包括所有必要的配置文件和依賴。
第二步：安裝依賴並啟動開發伺服器
bashcd my-vue-app
npm install
npm run dev
執行 npm run dev 後，Vite 會啟動開發伺服器，通常在 http://localhost:5173 上運行。此時你可以在瀏覽器中看到你的應用，並進行實時開發。開發伺服器會自動監聽文件變化，實現熱更新（Hot Module Replacement, HMR），無需手動刷新瀏覽器。
第三步：開發應用
項目結構
標準的 Vue 3 + Vite 項目結構如下：
textsrc/
├── components/ # 可復用組件
├── views/ # 頁面級組件
├── stores/ # Pinia store 文件
├── router/ # Vue Router 配置
├── App.vue # 根組件
└── main.js # 應用入口
public/ # 靜態資源
dist/ # 生產構建輸出（構建後生成）
package.json
vite.config.js
使用 Pinia 進行狀態管理
創建一個 Pinia store：
javascript// src/stores/counter.js
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
export const useCounterStore = defineStore('counter', () => {
const count = ref(0)
const doubled = computed(() => count.value * 2)
function increment() {
count.value++
}
return { count, doubled, increment }
})
在組件中使用：
text<template>
<div>
<p>Count: {{ store.count }}</p>
<p>Doubled: {{ store.doubled }}</p>
<button @click="store.increment">Increment</button>
</div>
</template>
<script setup>
import { useCounterStore } from '@/stores/counter'
const store = useCounterStore()
</script>
使用 Vue Router 構建 SPA
設置路由實現單頁應用：
javascript// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'
import Home from '@/views/Home.vue'
import About from '@/views/About.vue'
const routes = [
{ path: '/', component: Home },
{ path: '/about', component: About }
]
const router = createRouter({
history: createWebHistory(),
routes
})
export default router
在模板中使用導航：
text<template>
<nav>
<router-link to="/">Home</router-link>
<router-link to="/about">About</router-link>
</nav>
<router-view />
</template>
第三部分：生產構建
什麼是生產構建？
當完成開發後，你需要為生產環境創建優化版本。運行以下命令：
bashnpm run build
此命令將執行以下步驟：
- 代碼最小化（Minification）：移除所有不必要的字符，減小文件體積
- Tree-shaking：移除未使用的代碼
- 資源優化：壓縮圖片、CSS、JavaScript
- 產生最終產物：輸出到
/dist文件夾
生產構建後的輸出示例：
textdist/
├── index.html # 應用入口
├── assets/
│ ├── main-abc123.js # 最小化的 JavaScript
│ ├── style-def456.css # 最小化的 CSS
│ └── images/ # 優化後的圖片
└── favicon.ico
重要區別：開發 vs 生產
| 方面 | 開發環境 | 生產環境 |
|---|---|---|
| 命令 | npm run dev | npm run build |
| 文件大小 | 較大（含調試信息） | 最小化 |
| 性能 | 強調快速重編譯 | 強調運行效率 |
| 輸出位置 | 內存中（開發伺服器） | /dist 文件夾 |
| 用途 | 本地開發調試 | 生產部署 |
第四部分：部署 – 新手常見誤區
誤區一：直接在瀏覽器打開 index.html
錯誤做法
許多新手在構建完成後，會嘗試直接在瀏覽器中打開 dist/index.html 文件：
text文件位置：C:\Users\YourName\project\dist\index.html
在瀏覽器中打開 → 結果：白屏或 CORS 錯誤
為什麼會失敗？
當直接打開 HTML 文件時，瀏覽器使用 file:// 協議而非 http:// 或 https:// 協議。這會導致多個問題：
- CORS 限制瀏覽器的同源策略阻止跨域請求
- 路由失敗：Vue Router 依賴服務器配置來正確處理 SPA 路由，當用戶刷新頁面時，瀏覽器會直接向文件系統請求資源而不是向服務器請求
- 模塊加載失敗：JavaScript 模塊無法正確加載
正確做法
必須通過 web 伺服器以 http:// 或 https:// 協議提供文件。有多種方式可實現：
方式一：本地測試（快速驗證）
使用 Node.js 的 serve 工具：
bashnpm install -g serve
serve -s dist
此命令將在 http://localhost:3000 上啟動本地伺服器。
方式二：使用 Vite 預覽（快速檢查）
bashnpm run preview
此命令使用 Vite 內置的預覽伺服器，但仅用於本地測試，不適用於生產環境。
誤區二：不理解 SPA 路由配置
什麼是 SPA 路由問題？
單頁應用（SPA）使用 HTML5 History API 在客戶端處理路由。例如，用戶訪問：
texthttps://example.com/about
https://example.com/products/123
這些 URL 實際上都由同一個 index.html 處理，所有的路由邏輯發生在瀏覽器中。然而，當用戶直接訪問這些 URL 或刷新頁面時，瀏覽器會向伺服器發送請求。如果伺服器没有正確配置，它會返回 404 錯誤，因為伺服器上不存在 /about 或 /products/123 這樣的物理文件。
解決方案：配置 web 伺服器
不同的伺服器需要不同的配置來將所有請求重定向到 index.html：
Apache（使用 .htaccess）
在 dist/ 文件夾中創建 .htaccess 文件：
text<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]
</IfModule>
Nginx
在 Nginx 配置中添加：
textserver {
listen 80;
server_name example.com;
root /var/www/dist;
location / {
try_files $uri $uri/ /index.html;
}
}
Vercel（自動配置）
Vercel 會自動檢測 Vue 應用並配置 SPA 路由，無需手動設置。
Netlify（自動配置）
Netlify 也會自動處理 SPA 路由，無需額外配置。
誤區三：誤解什麼應該被部署
正確做法
部署時，應該上傳 dist/ 文件夾的 內容，而不是文件夾本身：
bash# 正確：上傳 dist 文件夾內的所有文件
✓ index.html
✓ assets/main-abc123.js
✓ assets/style-def456.css
✓ favicon.ico
# 錯誤：上傳 dist 文件夾本身
✗ dist/index.html
✗ dist/assets/...
常見的共享主機部署步驟：
bash1. npm run build
2. 使用 FTP 客戶端連接到主機
3. 進入 public_html 或指定目錄
4. 上傳 dist 文件夾內的所有文件
5. 創建子域名指向該目錄（可選）
第五部分：部署選項對比
不同的部署平台提供不同的優勢和複雜度：
| 平台 | 易用性 | 配置需求 | 自動化 | 成本 |
|---|---|---|---|---|
| Netlify | 很高 | 最小 | Git 自動部署 | 免費/付費 |
| Vercel | 很高 | 最小 | Git 自動部署 | 免費/付費 |
| Cloudflare Pages | 高 | 最小 | Git 自動部署 | 免費/付費 |
| GitHub Pages | 中等 | 中等 | 自動化腳本 | 免費 |
| Firebase Hosting | 中等 | 中等 | 自動化 | 免費/付費 |
| 共享主機 | 低 | 需要 .htaccess | 手動 | 低 |
| AWS S3 | 低 | 複雜配置 | 手動/自動化 | 按使用量 |
推薦新手選擇
對於初學者，推薦使用 Netlify 或 Vercel，因為它們提供最簡單的部署流程：
- 將代碼推送到 GitHub
- 在 Netlify/Vercel 上連接 GitHub 倉庫
- 自動部署完成
第六部分：常見問題解答
Q1：為什麼在開發中需要 npm run dev 而不是直接打開 HTML？
開發伺服器提供熱更新功能，讓你在修改代碼時無需手動刷新瀏覽器。它還處理模塊解析、資源加載等複雜任務。
Q2：Pinia 一定要使用嗎？
不一定。對於簡單應用，可以使用 Vue 的 prop drilling 或 provide/inject 機制。但對於中等以上複雜度的應用，Pinia 的集中狀態管理會大大簡化代碼。
Q3：dist 文件夾能不能提交到 Git？
建議不提交。dist/ 文件夾應該被加入 .gitignore，因為它可以從源代碼重新生成。這樣可以保持倉庫精簡，並避免部署時的衝突。
Q4：能否在 dist 文件夾中修改文件而不重新構建？
強烈不建議。dist/ 中的代碼經過了最小化和優化，難以手動編輯。任何修改在重新構建時都會丟失。始終在 src/ 中修改源代碼，然後重新構建。
Q5：開發環境和生產環境的文件大小差異有多大？
通常能減少 60-80% 的文件大小。例如，一個開發版本可能有 500KB，而生產版本可能只有 100KB。
Q6：如何在不同環境中使用不同的 API 地址？
使用環境變量。Vite 支持 .env 文件：
text.env.development
VITE_API_URL=http://localhost:3001
.env.production
VITE_API_URL=https://api.example.com
在代碼中使用：
javascriptconst apiUrl = import.meta.env.VITE_API_URL
總結
Vue 3 + Vite + Pinia 的組合提供了現代、高效的前端開發體驗。關鍵要點總結如下：
- 開發流程：
npm run dev啟動開發伺服器，進行本地開發和調試 - Pinia 狀態管理：使用官方的、輕量級的狀態管理方案
- 生產構建：
npm run build生成優化版本到/dist文件夾 - 部署：必須通過 web 伺服器提供 SPA，配置正確的路由重寫規則
- 避免誤區：不能直接打開 index.html，必須使用 http(s) 協議
掌握這些基礎概念後，你就能夠有效地開發和部署現代 Vue 應用。
參考資源
- Vite 官方文檔[oreateai]
- Vue 3 快速開始[vuejs]
- Pinia 官方文檔[pinia.vuejs]
- Vue Router 官方指南[vuejs]
- Vite 部署指南[vite]
