一、前言：为什么需要 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）刷新环境变量。