Vue 3 基礎概念：安裝與開發環境建立（npm、Vite、Vue‑CLI）

簡介

在開發 Vue 3 應用程式之前，先把開發環境妥善配置好是成功的關鍵。現代前端開發已經脫離了傳統的手動引入 script 標籤，改以 npm 這套套件管理工具統一管理依賴，並搭配 Vite 或 Vue‑CLI 這類建置工具提供即時模組熱更新（HMR）與快速編譯的開發體驗。

本篇文章將從零開始說明如何使用 npm 安裝 Node.js、建立專案、選擇 Vite 或 Vue‑CLI 兩條主流路線，並提供完整的範例程式碼。即使你是剛接觸前端的初學者，或是已經有一定 JavaScript 基礎的中級開發者，都能在閱讀完本篇後，立即在本機跑起第一個 Vue 3 應用。

---

核心概念

1. 為什麼需要 npm？

• 套件管理：npm（Node Package Manager）是 Node.js 的官方套件庫，所有 Vue、Vite、Vue‑CLI 以及第三方插件都以 npm 套件的形式發佈。
• 版本控制：透過 package.json 記錄每個相依套件的版本，讓團隊成員可以在不同機器上取得完全相同的開發環境。
• 腳本自動化：npm 允許在 scripts 區段自訂常用指令（如 npm run dev、npm run build），讓建置、測試、部署變得一鍵完成。

小技巧：在安裝全域套件（如 vite、@vue/cli）時加上 -g 參數；若只在單一專案使用，建議改為本地安裝，避免版本衝突。

2. Vite：下一代前端建置工具

Vite（法文「快速」之意）是由 Vue 官方創始人尤雨溪開發的開發伺服器與打包工具，特別針對 原生 ES 模組（ESM）進行優化，具備以下特點：

特點	說明
即時熱更新（HMR）	只重載變更的模組，開發時幾乎感覺不到延遲。
原生 ESM	開發階段直接使用瀏覽器支援的 ES 模組，不需要事先打包。
極速啟動	無需整體編譯，啟動時間通常在 0.5 秒以內。
可擴充	支援插件系統，官方提供 Vue、React、Svelte 等插件。

2.1 建立 Vite + Vue 3 專案的步驟

# 1. 確認已安裝 Node.js（建議 16+）
node -v

# 2. 使用 npm 直接呼叫 Vite 建立 Vue 3 專案
npm create vite@latest my-vue3-app -- --template vue

# 3. 進入專案目錄並安裝相依套件
cd my-vue3-app
npm install

# 4. 啟動開發伺服器
npm run dev

註解：npm create vite@latest 會自動下載最新的 Vite 建置腳本，--template vue 代表使用 Vue 3 官方範本。執行 npm run dev 後，預設會在 http://localhost:5173 開啟應用。

2.2 Vite 設定檔（vite.config.js）簡介

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],          // 啟用 Vue 3 支援
  server: {
    port: 3000,              // 開發伺服器預設埠號，可自行調整
    open: true               // 啟動後自動開啟瀏覽器
  },
  build: {
    outDir: 'dist',          // 打包產出目錄
    sourcemap: true          // 產生 source map，方便除錯
  }
})

3. Vue‑CLI：傳統且功能完整的腳手架

在 Vite 出現之前，Vue‑CLI 是官方推薦的腳手架工具。它以 Webpack 為底層，提供完整的插件機制與 UI（vue ui）介面，適合需要較多自訂 Webpack 設定的情境。

3.1 全域安裝 Vue‑CLI

# 安裝最新的 Vue CLI（建議使用 npx 直接執行，避免全域衝突）
npm install -g @vue/cli

# 檢查版本
vue --version

3.2 使用 Vue‑CLI 建立 Vue 3 專案

# 建立新專案，名稱為 my-vue3-cli
vue create my-vue3-cli

# 互動式選單出現時，選擇「Manually select features」
# 勾選以下項目：
#   - Babel
#   - TypeScript (若需要)
#   - Router
#   - Vuex (或 Pinia)
#   - Linter / Formatter
#   - Unit Testing (視需求而定)
# 接著選擇 Vue 版本為 3.x，最後完成安裝

3.3 常見 Vue‑CLI 設定檔

• vue.config.js：自訂 Webpack 設定、代理（proxy）等。

module.exports = {
  // 設定開發伺服器的代理，解決跨域問題
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:5000',
        changeOrigin: true,
        pathRewrite: { '^/api': '' }
      }
    }
  },
  // 修改預設的打包目錄
  outputDir: 'build',
  // 關閉產生的 source map（正式環境建議關閉）
  productionSourceMap: false
}

4. npm Scripts：統一管理開發指令

指令	說明
npm run dev	Vite 或 Vue‑CLI 開發伺服器（熱更新）
npm run build	打包成靜態檔案（dist 或 build）
npm run serve	使用 vite preview 或 vue-cli-service serve 預覽打包結果
npm run lint	執行 ESLint 檢查程式碼風格
npm run test:unit	執行單元測試（若有設定）

提醒：在 package.json 中自行新增或調整腳本時，保持指令簡潔且與團隊共識一致，避免日後產生混亂。

---

程式碼範例

以下提供 5 個實務上常會用到的範例，從安裝套件到建立簡易元件，逐步展示開發流程。

範例 1：安裝 Vue 3、Vue Router、Pinia（狀態管理）

# 在 Vite 專案中安裝常用套件
npm i vue@next vue-router@4 pinia@2

範例 2：設定 Vue Router（src/router/index.js）

import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '@/views/HomeView.vue'
import AboutView from '@/views/AboutView.vue'

const routes = [
  { path: '/', name: 'Home', component: HomeView },
  { path: '/about', name: 'About', component: AboutView }
]

export default createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

重點：createWebHistory 會使用 HTML5 History API，讓 URL 看起來更乾淨。

範例 3：使用 Pinia 建立全域狀態（src/stores/counter.js）

import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0
  }),
  getters: {
    doubleCount: (state) => state.count * 2
  },
  actions: {
    increment() {
      this.count++
    }
  }
})

在元件中使用：

<script setup>
import { useCounterStore } from '@/stores/counter'

const counter = useCounterStore()
</script>

<template>
  <button @click="counter.increment()">點我 +1</button>
  <p>目前計數：{{ counter.count }}（雙倍：{{ counter.doubleCount }}）</p>
</template>

範例 4：Vite 中的環境變數（.env、.env.production）

# .env
VITE_API_URL=https://dev.api.example.com
VITE_APP_TITLE=My Vue3 App

// 任何 .js/.vue 檔案中都可以這樣取得
const apiUrl = import.meta.env.VITE_API_URL
document.title = import.meta.env.VITE_APP_TITLE

提示：所有自訂環境變數必須以 VITE_ 為前綴，才會被 Vite 曝露給前端程式。

範例 5：在 Vue‑CLI 中使用自訂 Webpack Loader（例如 svg-sprite-loader）

npm i -D svg-sprite-loader

vue.config.js：

module.exports = {
  chainWebpack: (config) => {
    const svgRule = config.module.rule('svg')
    // 移除預設的 svg 處理
    svgRule.uses.clear()
    // 使用自訂 loader
    svgRule
      .use('svg-sprite-loader')
      .loader('svg-sprite-loader')
      .options({ symbolId: 'icon-[name]' })
  }
}

在元件中使用：

<svg class="icon"><use href="#icon-home"></use></svg>

---

常見陷阱與最佳實踐

陷阱	說明	解決方案 / 最佳實踐
Node 版本不一致	使用舊版 Node 會導致 Vite/Vue‑CLI 安裝失敗。	使用 nvm（Node Version Manager）統一版本，建議 LTS 16+。
全域安裝與本地版本衝突	全域 vite 與專案內 vite 版本不一致，指令可能呼叫錯誤。	盡量使用 npx vite 或在 package.json 中加入腳本，避免全域依賴。
環境變數漏寫前綴	Vite 只會暴露以 VITE_ 開頭的變數，其他會被剔除。	務必 在 .env 檔案中加上 VITE_ 前綴，並在程式碼中使用 import.meta.env。
Webpack 設定過度客製化	在 Vue‑CLI 中直接改寫 Webpack，可能導致升級困難。	使用 vue.config.js 的 chainWebpack 或 configureWebpack，保持設定可讀且易於維護。
忘記安裝相依套件	直接執行 npm run dev 卻顯示模組找不到。	每次 拉取新分支或克隆倉庫後，先執行 npm install。
開發伺服器端口衝突	預設 5173（Vite）或 8080（Vue‑CLI）被其他服務佔用。	在設定檔中修改 server.port，或使用 npm run dev -- --port 3001 直接覆寫。

最佳實踐：

1. 使用 .npmrc 設定 registry：在團隊內部使用私有 npm registry 時，於根目錄加入 .npmrc，確保安裝一致。
2. 加入 Prettier + ESLint：在 package.json 中加入 "lint": "eslint --ext .js,.vue src"，保持程式碼風格統一。
3. Git Hook（husky）：在提交前自動執行 lint，減少不良程式碼流入主分支。
4. 分離開發與生產環境：使用 Vite 的 mode（npm run dev -- --mode staging）或 Vue‑CLI 的 --mode 參數，避免將測試 API 佈署到正式環境。

---

實際應用場景

場景	建議工具	為什麼適合
快速原型（POC）	Vite	極速啟動、即時 HMR，讓 UI 改動立刻看到結果。
大型企業專案、需要自訂 Webpack	Vue‑CLI	完整的插件生態、支援多種 Loader，且內建 UI (vue ui) 方便管理。
需要多環境變數（dev、staging、prod）	Vite + .env.[mode]	Vite 自動根據 mode 載入對應檔案，簡化設定。
團隊協作、統一 lint & formatting	任一工具 + ESLint + Prettier + husky	讓每位開發者的編輯器環境保持一致，降低合併衝突。
SSR（Server‑Side Rendering）或 Nuxt 2/3	Vue‑CLI（配合 @vue/cli-plugin-ssr）或 Vite（配合 vite-ssr）	兩者皆有相應插件，可依專案需求選擇。

---

總結

• npm 是前端套件管理與腳本自動化的核心，透過 package.json 能夠確保團隊環境一致。
• Vite 以原生 ES 模組為基礎，提供近乎即時的開發體驗，特別適合 快速開發、小型專案 或 原型設計。
• Vue‑CLI 雖然在速度上稍遜於 Vite，但其 Webpack 的彈性與完整的插件系統，使其仍是 大型、需要深度客製化 專案的首選。
• 正確設定 環境變數、npm scripts、以及 Lint/Prettier，能讓開發流程更流暢、除錯更快速。
• 面對不同的實務需求，了解兩者的優缺點，才能在專案初期就選擇最合適的開發工具，減少後續重構成本。

掌握了 npm、Vite、Vue‑CLI 的安裝與設定，你已經完成了 Vue 3 開發的第一步。接下來，只要持續練習元件開發、路由與狀態管理，就能在實務專案中發揮 Vue 3 的強大威力。祝開發順利，玩得開心！ 🚀