【Vue2手錄11】Vue腳手架（@vue_cli）詳解（環境搭建+項目開發示例）

一、前言：為什么需要 Vue 腳手架？

手動搭建 Vue 項目存在諸多痛點（原筆記提及）：

依賴管理復雜：需手動下載 Vue、Babel、Webpack 等工具，處理版本兼容性。
配置繁瑣：Webpack 配置、ES6 轉碼、Vue 組件加載器等需手動編寫，易出錯。
開發體驗差：缺乏代碼提示、自動補全，CSS 無組件級隔離。

Vue 腳手架（@vue/cli）是官方提供的「環境搭建工具」，可 一鍵完成依賴安裝、配置生成、項目初始化，將手動幾小時的工作縮短到幾分鐘，是企業級 Vue 項目的標準開發方式。

二、環境準備（核心依賴：Node.js）

Vue 腳手架基于 Node.js 運行，需先安裝 Node.js（自帶 npm 包管理工具）。

2.1 Node.js 安裝步驟

下載 Node.js：
訪問 Node.js 官網，選擇 LTS 版本（長期支持版，穩定），根據系統（Windows/macOS）下載安裝包。

安裝過程：
- Windows：雙擊安裝包，全程默認下一步，務必勾選「Add to PATH」（自動配置環境變量，關鍵！）。

- macOS：雙擊 `.pkg` 文件，按提示完成安裝（默認配置環境變量）。

驗證安裝：
打開命令行工具（Windows：cmd/PowerShell；macOS：終端），輸入以下命令，顯示版本號即安裝成功：

node -v  # 查看 Node 版本（如 v18.16.0）
npm -v   # 查看 npm 版本（如 v9.5.1）

2.2 環境變量問題（常見坑）

問題現象：命令行輸入 node -v 提示「不是內部或外部命令」。
原因：安裝時未勾選「Add to PATH」，Node.js 路徑未加入系統環境變量。
解決方案：
1. Windows：手動添加環境變量（右鍵「此電腦」→「屬性」→「高級系統設置」→「環境變量」→「Path」→ 添加 Node 安裝路徑，如 C:\Program Files\nodejs\）。
2. 重啟命令行工具（環境變量修改后需重啟生效）。

三、npm 包管理工具（基礎必備）

npm（Node Package Manager）是 Node.js 自帶的包管理工具，用于下載、管理前端依賴（如 Vue、jQuery、axios 等）。

3.1 npm 核心概念

中央倉庫：npm 官方維護的代碼庫，存儲全球開源的 JavaScript 包（無需手動到各官網下載）。
依賴目錄：執行 npm install 時，包會下載到項目根目錄的 node_modules 文件夾（自動創建）。
版本控制：通過 package.json 和 package-lock.json 管理依賴版本，確保項目在不同環境下依賴一致。

3.2 npm 常用命令（實戰高頻）

命令	作用	示例
`npm init`	初始化項目，生成 `package.json` 文件	`npm init`（交互式配置）/ `npm init -y`（快速默認配置）
`npm install <包名>`	安裝依賴到項目（局部安裝）	`npm install vue`（安裝 Vue）
`npm install -g <包名>`	全局安裝依賴（所有項目可用）	`npm install -g @vue/cli`（安裝 Vue 腳手架）
`npm uninstall <包名>`	卸載項目依賴	`npm uninstall vue`（卸載 Vue）
`npm run <腳本名>`	執行 `package.json` 中的腳本	`npm run serve`（啟動 Vue 項目）

3.3 關鍵配置文件（理解核心）

3.3.1 `package.json`（項目說明書）

生成方式：npm init 或腳手架自動生成。
核心作用：
1. 記錄項目元數據（名稱、版本、描述、作者）。
2. 記錄項目依賴（dependencies：生產依賴；devDependencies：開發依賴）。
3. 定義項目腳本（如 scripts: { "serve": "vue-cli-service serve" }）。
示例結構：

{"name": "my-vue-project",  // 項目名稱"version": "1.0.0",        // 項目版本"dependencies": {          // 生產依賴（項目運行必需）"vue": "^2.6.14"         // Vue 版本},"scripts": {               // 項目腳本"serve": "vue-cli-service serve",  // 啟動開發服務器"build": "vue-cli-service build"   // 打包項目}
}

3.3.2 `package-lock.json`（版本鎖定文件）

生成方式：執行 npm install 時自動生成，無需手動修改。
核心作用：
鎖定所有依賴的 精確版本（包括間接依賴），避免后續安裝時因版本更新導致項目報錯（解決「我這能跑，你那跑不了」的問題）。
注意：提交代碼時需將此文件一并提交到 Git，確保團隊依賴版本一致。

四、Vue 腳手架（@vue/cli）實戰

4.1 腳手架全局安裝

腳手架需 全局安裝（一次安裝，所有項目可用），命令如下：

npm install -g @vue/cli

驗證安裝：輸入以下命令，顯示版本號即成功（如 @vue/cli 5.0.8）：

vue --version  # 或 vue -V（大寫 V）

4.2 用腳手架創建 Vue 2 項目（關鍵步驟）

4.2.1 步驟 1：選擇項目目錄

打開命令行，切換到目標文件夾（如 D:\projects），命令如下：

# Windows：切換到 D 盤
D:
# 進入 projects 文件夾
cd D:\projects
# macOS：進入用戶目錄下的 projects 文件夾
cd ~/projects

快捷技巧：在資源管理器中打開目標文件夾，地址欄輸入 cmd（Windows）或 terminal（macOS），可直接定位到當前目錄。

4.2.2 步驟 2：創建項目

執行以下命令，my-vue2-project 為項目名稱（必須英文，禁止中文/特殊符號）：

vue create my-vue2-project

4.2.3 步驟 3：選擇項目配置

選擇預設：
腳手架提供 3 種預設，初學者建議手動配置（Manually select features），便于理解項目結構：

? Please pick a preset: (Use arrow keys)
? Default ([Vue 3] babel, eslint)Default ([Vue 2] babel, eslint)Manually select features  # 手動選擇配置

手動選擇配置項：
按 空格鍵 選中/取消，選中以下 2 項即可（其他項后期可按需添加）：

? Check the features needed for your project: (Press <space> to select, <a> to toggle all, <i> to invert selection)
?? Babel  # 必選，用于 ES6 轉 ES5（兼容舊瀏覽器）? TypeScript  # 可選，TypeScript 支持? Progressive Web App (PWA) Support  # 可選，PWA 支持? Router  # 可選，路由（后期可裝）? Vuex  # 可選，狀態管理（后期可裝）? CSS Pre-processors  # 可選，CSS 預處理器（如 Sass）? Linter / Formatter  # 可選，代碼格式檢查（初學者建議不選，避免嚴格報錯）? Unit Testing  # 可選，單元測試? E2E Testing  # 可選，端到端測試

選擇 Vue 版本：
明確選擇 Vue 2（課程重點）：

? Choose a version of Vue.js that you want to start the project with (Use arrow keys)3.x
? 2.x

注：如果需要選擇ESLint（代碼質量檢查）

后續配置：
- 詢問「Where do you prefer placing config for Babel…」：選擇「In dedicated config files」（單獨生成配置文件，清晰）。
- 詢問「Save this as a preset for future projects?」：選擇「n」（不保存為預設，后續可靈活配置）。

4.2.4 步驟 4：啟動項目

cd my-vue2-project

啟動開發服務器：

npm run serve

訪問項目：
命令行顯示以下信息，打開瀏覽器訪問 http://localhost:8080，即可看到 Vue 歡迎頁面：

DONE  Compiled successfully in 3000msApp running at:
- Local:   http://localhost:8080/
- Network: http://192.168.1.100:8080/Note that the development build is not optimized.
To create a production build, run npm run build.

注：啟動報錯提示的排查步驟

首先使用管理員身份啟動VSCode，重啟軟件觀察是否正常運行。

要解決 PowerShell 中 npm 無法識別的問題，需分步驟排查 Node.js 安裝狀態 和 PowerShell 執行策略，以下是詳細解決方案：

驗證 Node.js 是否正確安裝

npm 是 Node.js 的包管理工具，若 Node.js 未安裝或環境變量配置錯誤，會導致 npm 命令失效。

打開新的 PowerShell 窗口（避免舊會話緩存問題）。
執行以下命令，檢查 Node.js 和 npm 是否安裝成功：

node -v   # 檢查 Node.js 版本（如輸出 v20.15.0）
npm -v    # 檢查 npm 版本（如輸出 10.5.0）

- **如果命令輸出版本號**：說明 Node.js 安裝正常，問題出在 PowerShell 執行策略（繼續看步驟 2）。  
- **如果命令報錯**（如“不是內部或外部命令”）：說明 Node.js 未安裝或環境變量未配置（跳轉到步驟 3）。

修復 PowerShell 執行策略（Node.js 已安裝但 `npm` 仍報錯）

Windows PowerShell 默認禁止運行未簽名腳本（如 npm.ps1），需修改執行策略。

以管理員身份打開 PowerShell：
- 按下 Win + X，選擇「Windows PowerShell (管理員)」或「終端 (管理員)」。或者在開始菜單中搜索PowerShell并打開。

查看當前執行策略：

Get-ExecutionPolicy

- 若輸出 `Restricted` 或 `AllSigned`，說明執行策略禁止運行腳本。

**修改執行策略為 **RemoteSigned（允許本地腳本運行，兼顧安全性）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

- 按提示輸入 `Y` 確認更改。

重啟 PowerShell：
關閉所有 PowerShell 窗口，重新打開普通 PowerShell（無需管理員），再次嘗試 npm run serve。

重新安裝 Node.js（Node.js 未安裝或環境變量錯誤）

若 node -v 和 npm -v 均報錯，說明 Node.js 安裝失敗或環境變量未配置。

卸載舊 Node.js（若已安裝但配置錯誤）：
- 打開「控制面板 → 程序和功能」，找到 Node.js 并卸載。
- 刪除安裝目錄（如 C:\Program Files\nodejs\）和 npm 緩存（C:\Users\你的用戶名\AppData\Roaming\npm）。
重新下載并安裝 Node.js LTS 版：
- 訪問 Node.js 官網，下載 LTS 版本（長期支持版，如 18.16.0）。
- 安裝時務必勾選“Add to PATH”選項（自動配置環境變量，關鍵步驟！）。
驗證安裝：
重啟終端，執行 node -v 和 npm -v，若輸出版本號則安裝成功。

額外建議：使用 Git Bash 或 CMD 臨時規避

若 PowerShell 問題仍未解決，可臨時切換到其他終端工具：

Git Bash：需安裝 Git，終端對 npm 支持更友好。
CMD：Windows 自帶的命令提示符，執行 npm run serve 通常不會有執行策略限制。

腳手架啟動后默認頁面

4.3 腳手架項目結構解析（核心目錄/文件）

腳手架生成的項目結構清晰，核心開發目錄為 src，其他多為配置/依賴文件：

目錄/文件	作用
`node_modules/`	存儲項目所有依賴（npm 安裝的包），體積大，無需提交 Git（`.gitignore` 已排除）
`public/`	靜態資源目錄（不被 Webpack 處理），如入口 HTML、圖標
├─ `index.html`	項目入口 HTML，Vue 實例會掛載到 `#app` 元素上
└─ `favicon.ico`	網站圖標
`src/`	核心開發目錄，所有業務代碼在此編寫
├─ `assets/`	靜態資源目錄（被 Webpack 處理），如圖片、CSS 文件
├─ `components/`	自定義組件目錄（如 `HelloWorld.vue`）
├─ `App.vue`	根組件（項目最頂層組件，包含其他子組件）
└─ `main.js`	項目入口 JS，初始化 Vue 實例并掛載到 DOM
`package.json`	項目說明書，記錄依賴和腳本
`package-lock.json`	依賴版本鎖定文件
`.gitignore`	Git 忽略文件配置（如 `node_modules/`、`dist/` 不提交 Git）

4.3.1 核心文件詳解

src/main.js（入口 JS）：
初始化 Vue 實例，掛載到 public/index.html 的 #app 元素上：

import Vue from 'vue'  // 引入 Vue
import App from './App.vue'  // 引入根組件 AppVue.config.productionTip = false  // 關閉生產環境提示new Vue({render: h => h(App)  // 將 App 組件渲染到 DOM
}).$mount('#app')  // 掛載到 #app 元素（等價于 el: '#app'）

src/App.vue（根組件）：
Vue 單文件組件（.vue），包含 template（HTML）、script（JS）、style（CSS）三部分：

<template><!-- 組件 HTML 結構（必須有且只有一個根元素） --><div id="app"><img src="./assets/logo.png"><!-- 引入子組件 HelloWorld --><HelloWorld msg="Welcome to Your Vue.js App"/></div>
</template>
<script>// 引入子組件import HelloWorld from './components/HelloWorld.vue'export default {name: 'App',  // 組件名components: {HelloWorld  // 注冊子組件}}
</script>
<style>/* 組件樣式（scoped 表示樣式僅作用于當前組件，避免污染） */#app {font-family: Avenir, Helvetica, Arial, sans-serif;text-align: center;color: #2c3e50;margin-top: 60px;}
</style>

src/components/HelloWorld.vue（子組件）：
自定義子組件，可在根組件 App.vue 中復用，結構與 App.vue 一致。

五、常見問題與解決方案（實戰避坑）

5.1 腳手架安裝后 `vue` 命令報錯（Windows）

問題現象：PowerShell 輸入 vue --version 提示「無法加載文件 … vue.ps1，因為在此系統上禁止運行腳本」。
原因：Windows PowerShell 執行策略限制（默認禁止運行未簽名腳本）。
解決方案：
1. 改用 cmd 命令行（Windows 自帶，無此限制）。
2. 或用管理員身份運行 PowerShell，執行以下命令修改策略：

Set-ExecutionPolicy RemoteSigned  # 按 Y 確認

5.2 啟動項目報錯「Port 8080 is already in use」

問題現象：npm run serve 提示 8080 端口被占用。
原因：其他程序（如 Tomcat、其他 Vue 項目）正在使用 8080 端口。
解決方案：
1. 關閉占用端口的程序。
2. 或修改 Vue 項目端口：在 package.json 的 scripts 中添加 --port 8081：

"scripts": {"serve": "vue-cli-service serve --port 8081",  // 改用 8081 端口"build": "vue-cli-service build"
}

5.3 VS Code 終端無法識別 `vue` 命令

問題現象：VS Code 內置終端輸入 vue --version 提示「不是內部或外部命令」。
原因：VS Code 未加載最新的環境變量（安裝 Node.js 或腳手架后未重啟 VS Code）。
解決方案：
1. 完全關閉 VS Code 并重新打開。
2. 或在 VS Code 終端中執行 source ~/.bash_profile（macOS）或 refreshenv（Windows）刷新環境變量。