脚手架搭建：Vite 创建 Vue/React 项目

第 2 章 · 脚手架搭建：Vite 创建 Vue/React 项目

本章目标：理解脚手架是什么、为何选用 Vite 而非 Vue CLI / CRA；能手把手执行 npm create vite@latest 的每一步交互选项；创建 academy-demo-vue 与 academy-demo-react；读懂 package.json 与 vite.config.js；掌握 install / dev / build / preview 全流程；配置 .env 与 dev server 代理贤紫 API；安装 vue-router、pinia、react-router-dom；能根据终端输出判断「首次运行成功」；独立完成 vanilla-ts 练习项目。

学时建议：3～4 小时（含 90 分钟跟练）

前置：完成 ch01（Node、npm 镜像、Git、工作区目录 frontend-framework-lab 已就绪）。

2.1 什么是脚手架？为何不用 Vue CLI / CRA

脚手架（Scaffold） = 官方或社区提供的项目生成器：一条命令生成标准目录、package.json、构建配置、示例页面，让你从「空白文件夹」直接进入「可 npm run dev」状态。

没有脚手架的时代                有 Vite 脚手架
  手写 index.html                  npm create vite
  手写 webpack 配置        →       选 vue / react
  配 babel、热更新                 npm install && npm run dev
  （半天～数天）                   （约 5 分钟）

工具	状态（2025）	说明
Vite	✅ 主流首选	极速冷启动、ESM 原生、Vue/React 官方推荐
Vue CLI	⚠️ 维护模式	基于 Webpack，新项目不推荐
Create React App (CRA)	❌ 已过时	React 官方已不建议新项目使用
Next.js / Nuxt	进阶	全栈 SSR，本模块 ch03 起先学 SPA

行业案例 · 贤紫优选商城：2024 年起新后台与学院 academy-demo 统一 Vite 5 + Vue 3；老 Webpack 项目仅维护不新建。

2.2 `npm create vite@latest` 交互式全流程

2.2.1 命令形式说明

# 非交互：直接指定项目名与模板（学院跟练推荐）
npm create vite@latest <项目名> -- --template <模板>

# 交互：逐步问答（理解选项时用）
npm create vite@latest

npm create vite@latest 等价于 npx create-vite@latest，会临时下载最新 create-vite 包并执行。

2.2.2 文字版模拟对话（交互模式）

下面是一次完整交互的文字截图，你在终端里会看到类似内容（版本号可能更新）：

$ npm create vite@latest

│
◇  Project name:
│  academy-demo-vue
│
◇  Select a framework:
│  ● Vue
│  ○ React
│  ○ …（其他框架略）
│
◇  Select a variant:
│  ● TypeScript
│  ○ JavaScript
│  ○ Official Vue Starter ↗
│  ○ ROLLDOWN-VITE ↗
│
◇  Scaffolding project in .../academy-demo-vue...
│
◇  Done. Now run:

  cd academy-demo-vue
  npm install
  npm run dev

提示项	含义	学院建议
Project name	文件夹名	`academy-demo-vue` / `academy-demo-react`
framework	框架	Vue 或 React
variant	语言	先选 JavaScript（ch03～ch07 再引入 TS）；练习可用 TypeScript

提示：非交互命令末尾的 -- 表示把后面参数传给 create-vite，避免 npm 吞掉 --template。

2.3 创建 academy-demo-vue（完整命令序列）

在 ch01 工作区 frontend-framework-lab 中执行（路径按机器调整）：

cd D:\dev\xianzi-academy\frontend-framework-lab

# 1. 生成 Vue + JavaScript 模板
npm create vite@latest academy-demo-vue -- --template vue

# 2. 进入项目
cd academy-demo-vue

# 3. 安装依赖（首次较慢，请耐心等待）
npm install

# 4. 启动开发服务器
npm run dev

成功后终端应出现（截图级描述）：

  VITE v5.4.11  ready in 382 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.105:5173/
  ➜  press h + enter to show help

浏览器打开 http://localhost:5173/，应看到：

页面中央 Vite + Vue Logo（Vue 绿色与 Vite 闪电）
标题区有 「Vite + Vue」 文案
一个计数按钮 count is 0，点击数字递增
底部链接 「Edit components/HelloWorld.vue to test HMR」

保持 npm run dev 运行，修改 src/components/HelloWorld.vue 中任意文字，浏览器无需刷新即更新 — 此为 HMR（热模块替换）。

按 Ctrl + C 停止 dev server。

2.4 创建 academy-demo-react（完整命令序列）

回到 frontend-framework-lab 同级目录：

cd D:\dev\xianzi-academy\frontend-framework-lab

npm create vite@latest academy-demo-react -- --template react

cd academy-demo-react
npm install
npm run dev

浏览器 http://localhost:5173/ 应看到：

Vite + React Logo（React 蓝色原子图标）
标题 「Vite + React」
计数器按钮 count is 0
提示编辑 src/App.jsx 测试 HMR

项目	入口组件	模板后缀
academy-demo-vue	`src/App.vue`	`.vue` 单文件组件
academy-demo-react	`src/App.jsx`	`.jsx`

两个项目不要同时占用 5173：先 Ctrl+C 停一个，或见 2.11 节改端口。

2.5 package.json 每个字段详解

以 academy-demo-vue 为例（React 项目结构类似，依赖名不同）：

{
  "name": "academy-demo-vue",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.5.13"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.1",
    "vite": "^6.0.3"
  }
}

字段	含义	说明
name	npm 包名	小写、连字符；发布到 npm 时才严格要求唯一
private	是否私有	`true` 防止误 `npm publish`
version	语义化版本	学院 demo 保持 `0.0.0` 即可
type: "module"	模块系统	项目内 `.js` 默认按 ESM 解析，`import/export`
scripts.dev	开发命令	启动 Vite dev server + HMR
scripts.build	生产构建	输出到 `dist/`，压缩、Tree Shaking
scripts.preview	本地预览构建结果	模拟生产环境静态服务
dependencies	运行时依赖	打进最终 bundle，如 `vue`、`react`
devDependencies	开发时依赖	仅构建/开发用，如 `vite`、插件
^ 版本号	兼容范围	`^3.5.13` 允许 3.x 最新，不升到 4.x

2.6 vite.config.js 逐行解释

在 academy-demo-vue 根目录创建或编辑 vite.config.js（若生成的是 .ts 可改为 .js 便于初学）：

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

// https://vitejs.dev/config/
export default defineConfig({
  // 插件：让 Vite 能编译 .vue 文件
  plugins: [vue()],

  // 开发服务器配置
  server: {
    port: 5173,           // 本地端口，被占用时可改 5174
    open: true,           // 启动时自动打开浏览器（可选）
    host: true,           // 允许局域网访问（手机真机调试）

    // 代理：把浏览器请求 /api 转发到贤紫 Django 后端，解决开发环境跨域
    proxy: {
      '/api': {
        target: 'http://localhost:8000',  // 贤紫本地 API 根地址
        changeOrigin: true,               // 修改请求头 Host，避免后端校验失败
        // rewrite: (path) => path.replace(/^\/api/, '/api/v1'),  // 按实际路径调整
      },
    },