用 Vite 建立現代 Vue 專案

歡迎來到《重新認識 Vue.js》第二版。開始寫 Vue 程式前，我們先把開發環境準備好，這就像做菜前需備妥廚房與爐具一樣。本章會從零建立一個現代的 Vue 專案，並認識日常開發常用的工具。

若你曾讀過本書第一版，會發現開發環境已與過往不同：我們不再使用 Vue CLI，而是全面改用 Vite。本節將說明此項變革的原因，並引導各位讀者如何著手。

為什麼是 Vite？

早期我們習慣使用 Vue CLI（底層為 webpack）來建立專案。它在當年雖然便利，但隨著專案規模增長，啟動開發伺服器與熱更新的速度會逐漸變慢，設定也較為繁瑣。

Vue 官方現在建議改用 Vite 作為建置工具。Vite 在開發模式下利用瀏覽器原生的 ES 模組 (ES Modules)，讓開發伺服器啟動更快，存檔後也能快速熱更新；正式打包時則交由 Rollup 處理。

小提醒

Vue CLI 目前已進入維護模式，未來不再新增功能。若你手邊仍有以 Vue CLI 建立的舊專案，它們依然可正常運作；但新專案建議優先使用 Vite。舊專案的維護說明，我們已整理於附錄與 1/e 封存。

事前準備：Node.js

依 Vue 官方 Quick Start，建立專案前需安裝 Node.js ^20.19.0 || >=22.12.0。版本門檻仍可能隨 Vite 與 create-vue 更新，實際請以建立專案時的提示與官方文件為準。

我們可以在終端機中輸入以下指令，確認當前的 Node.js 版本：

node -v

常見錯誤：Node 版本太舊

初學者常在此處受阻，若使用過舊的 Node.js 版本，create-vue 或 vite 會直接報錯或引發異常。

❌ 版本太舊：建立或啟動專案時出現一串難以判讀的錯誤訊息。
✅ 先升級 Node（建議用 nvm 之類的版本管理工具切換），再往下做。

本書的指令一律以 pnpm 示範（安裝速度快、節省磁碟空間）。若你習慣 npm 或 yarn，只需將 pnpm 替換為對應的套件管理指令即可。

建立專案：`pnpm create vue`

Vue 官方提供了鷹架工具 create-vue，一行指令就能建立一個以 Vite 為基礎的專案：

pnpm create vue@latest

執行後會進入互動式設定：系統會先提示輸入專案 (或套件) 名稱，接著詢問要包含哪些功能。本章我們先建立最小專案：進階功能選項先選 No，程式碼品質工具（ESLint / Prettier）可依喜好選 Yes 或 No。畫面大致如下：

✔ Project name: … my-vue-app
✔ Add TypeScript? … No
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … No
✔ Add Pinia for state management? … No
✔ Add Vitest for Unit Testing? … No
✔ Add an End-to-End Testing Solution? … No / Cypress / Nightwatch / Playwright
✔ Add ESLint for code quality? … Yes（可依喜好選擇）
✔ Add Prettier for code formatting? … Yes（可依喜好選擇）
✔ Add Vue DevTools 7 extension for debugging? … No（本章後續改用瀏覽器擴充功能安裝）

小提醒

create-vue 的互動選項與畫面樣式會隨版本調整 (例如較新版把 Oxlint 併入 ESLint、並新增 Oxfmt 格式化工具)，上面僅為示意。不必死記每個選項，看不懂的先選「不加入」即可，之後章節需要時再回頭補上。

如果你想跳過問答、或需要可重現的設定，也可以直接用旗標建立：

pnpm create vue@latest my-vue-app --default   # 最小預設設定
# 想要不含範例程式的最精簡骨架，可改用 --bare

建立完成後，照著畫面提示進入資料夾、安裝相依套件、啟動開發伺服器：

cd my-vue-app
pnpm install
pnpm dev

順利啟動後，終端機將顯示本機網址 (預設為 http://localhost:5173/)，以瀏覽器開啟即可看見 Vue 的歡迎畫面。至此，我們第一個現代化的 Vue 專案已順利運作。

專案裡有些什麼？

使用編輯器開啟剛剛建立的專案資料夾，將會看見大致如下的結構（create-vue 會附上幾個範例元件如 HelloWorld.vue，可自行刪改；未勾選的功能不會產生對應資料夾）：

my-vue-app/
├─ index.html          # 應用程式的主 HTML 檔案
├─ vite.config.js      # Vite 設定檔
├─ package.json        # 相依套件與指令
└─ src/
   ├─ main.js          # 應用程式進入點
   ├─ App.vue          # 根元件
   ├─ assets/          # 靜態資源（樣式、圖片等）
   └─ components/      # 可複用元件（檔名用 PascalCase）

後續加入 Router、Pinia 與組合式函式時，src/ 目錄下會相應產生 router/、stores/、composables/ 與 views/ 等資料夾。本書範例皆遵循此結構，以利對照。

其中最關鍵的是 src/main.js，它負責建立並掛載 Vue 應用程式：

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

createApp(App).mount('#app')

小提醒

在 Vue 2 中，我們是用 new Vue({...}) 來建立實體；到了 Vue 3，改用 createApp() 建立應用程式實體，再以 .mount() 掛載至頁面元素。此寫法將貫穿後續的所有章節。

開發與打包指令

package.json 中已預先定義好幾個常用指令，可以使用 pnpm 來執行：

pnpm dev       # 啟動開發伺服器（改檔即時更新）
pnpm build     # 打包成正式版，輸出到 dist/
pnpm preview   # 在本機預覽打包後的結果

日常開發主要使用 pnpm dev；在準備部署前，先執行 pnpm build 產出正式發行檔案，並透過 pnpm preview 預覽與確認打包後的結果。有關部署的詳細步驟，我們將在後續章節詳述。

環境準備好了，專案也跑起來了。接下來，我們來認識兩個能讓開發事半功倍的好夥伴：Vue DevTools 與 VS Code。

用 Vite 建立現代 Vue 專案 ​

為什麼是 Vite？ ​

事前準備：Node.js ​

建立專案：pnpm create vue ​