用 Vite 建立現代 Vue 專案

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

若你曾讀過本書第一版，會發現開發環境已與過往不同：我們不再使用 Vue CLI，而是全面改用 Vite。

為什麼是 Vite？

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

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

小提醒

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

事前準備：Node.js

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

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

node -v

常見錯誤：Node 版本太舊

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

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

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

建立專案：`pnpm create vue`

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

pnpm create vue@latest

執行後會進入互動式設定。系統會先詢問專案名稱（也是目標資料夾名稱）與是否使用 TypeScript，再以清單列出可加入的功能。本章先建立 JavaScript 最小專案：TypeScript 選 No，功能與實驗功能清單都不勾選，最後保留範例程式。畫面大致如下：

◆ Project name (target directory):
│ my-vue-app

◆ Use TypeScript?
│ No

◆ Select features to include in your project:
│ ◻ JSX Support
│ ◻ Router (SPA development)
│ ◻ Pinia (state management)
│ ◻ Vitest (unit testing)
│ ◻ End-to-End Testing
│ ◻ Linter (error prevention)
│ ◻ Prettier (code formatting)

◆ Select experimental features to include in your project:
│ ◻ Replace Prettier with Oxfmt
│ ◻ Vue 3.6 (beta)

◆ Skip all example code and start with a blank Vue project?
│ No

小提醒

create-vue 的互動選項與畫面樣式會隨版本調整，上面僅為示意。目前選擇 Linter 會同時加入 ESLint 與 Oxlint；實驗功能中的 Oxfmt 則會取代 Prettier。這些工具之後都能再加入，現在不確定用途時可以先不勾選。

Vue DevTools

create-vue 目前會在預設專案中加入 vite-plugin-vue-devtools，不會再顯示是否加入 DevTools 的問題。它與瀏覽器安裝的 Vue DevTools 擴充功能是兩種使用方式，下一節會再介紹後者。

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

pnpm create vue@latest my-vue-app --default          # 最小預設設定，保留範例程式
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，src/ 中還會有 router/ 與 views/；勾選 Pinia 則會有 stores/。組合式函式使用的 composables/ 不由 create-vue 自動產生，需要時再自行建立即可。本書範例皆遵循此結構，以利對照。

其中最關鍵的是 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 ​