第 1 章 Vite 项目初始化

本章导读

你将学会 ：从零用 Vite 创建 vue3-learn-demo 工程、看懂每个目录和文件的职责、掌握 npm 常用命令、跑通开发与打包全流程

前置要求 ：电脑已安装 Node.js 18 以上版本（终端执行 node -v 能出版本号）

预计用时：1～2 小时（留出排查环境问题的时间，零基础第一次装环境出问题很正常）

1.1 用 Vite 创建项目

【知识点讲解】

Vue3 官方推荐的构建工具是 Vite 。它做的事：开发时提供一个极速本地服务器（改代码浏览器秒级热更新），打包时把 .vue、.js、.css 编译压缩成浏览器能直接运行的静态文件。

企业里不存在"一个 html 引入 vue.js"的写法，所有项目都是脚手架工程化创建。你只需要记住一条命令：npm create vite。

前置条件：安装 Node.js ≥ 18（去 nodejs.org 下载 LTS 版本，一路下一步）。装好后打开终端执行 node -v 和 npm -v，能打印版本号即可。

【示例代码】

bash 复制代码

# 1. 进入你存放代码的目录（Windows 示例）
cd D:/projects

# 2. 创建项目（--template vue 表示使用原生 Vue3 + JS 模板）
npm create vite@latest vue3-learn-demo -- --template vue

# 3. 进入项目目录
cd vue3-learn-demo

# 4. 安装依赖
npm install

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

创建成功后的初始目录结构：

csharp 复制代码

vue3-learn-demo/
├── node_modules/         # 依赖包，npm install 自动生成，禁止手动改
├── public/               # 原样拷贝的静态资源（favicon.ico 等）
├── src/                  # 源代码，我们 99% 的工作都在这里
│   ├── assets/           # 图片、全局样式
│   ├── components/       # 组件
│   ├── App.vue           # 根组件
│   └── main.js           # 应用入口
├── index.html            # 整个项目唯一的 HTML（SPA 单页应用入口）
├── package.json          # 项目说明书：依赖、命令
└── vite.config.js        # Vite 配置文件

浏览器访问终端输出的地址（默认 http://localhost:5173），看到 Vite + Vue 欢迎页即成功。

【练习Demo】

需求：创建 vue3-learn-demo 项目并成功启动，然后把首页文案改成"我的第一个 Vue3 项目"。

参考实现：

xml 复制代码


<script setup>
// 暂时删除模板自带的 HelloWorld 组件引入，从零开始
import { ref } from 'vue'

const title = ref('我的第一个 Vue3 项目')
</script>

<template>
  <h1>{{ title }}</h1>
</template>

验证：保存后浏览器自动热更新，页面显示新文案。练习完成说明：项目创建 ✓、启动 ✓、.vue 文件可编辑 ✓。

1.2 npm 基础

【知识点讲解】

npm 是 Node.js 自带的包管理器，相当于"应用商店"：别人写好的功能（包）发布到 npmjs.com，你用命令下载到本地使用。

必须掌握的概念：

概念	说明
`package.json`	项目清单：叫什么、装了哪些依赖、有哪些命令
`dependencies`	生产依赖（`npm install xxx` 默认装这里），打包时会被打进产物
`devDependencies`	开发依赖（`npm install xxx -D`），只在开发时用，如 ESLint
`package-lock.json`	锁定每个依赖的精确版本，保证同事之间装出一样的依赖，要提交到 git，禁止手改
`node_modules`	依赖实体目录，体积巨大，禁止提交到 git

【示例代码】

perl 复制代码

# 安装生产依赖（默认）
npm install vue-router@4

# 安装开发依赖（-D 是 --save-dev 的缩写）
npm install -D sass

# 安装 package.json 里声明的全部依赖（克隆项目后第一件事）
npm install

# 查看已安装的 vue 版本
npm list vue

json 复制代码

// 文件：package.json（脚手架生成后核心字段解读）
{
  "name": "vue3-learn-demo",
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",           // 开发：启动本地服务器
    "build": "vite build",   // 打包：生成 dist 目录
    "preview": "vite preview" // 预览：本地跑打包产物，验证 build 结果
  },
  "dependencies": {
    "vue": "^3.5.13"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.1",
    "vite": "^6.0.1"
  }
}

【练习Demo】

需求：查看当前项目 vue 和 vite 的版本，并给项目新增一条脚本命令 npm run hello，执行时在终端输出 hello vue3。

参考实现：

json 复制代码

// 文件：package.json（修改 scripts 部分）
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "hello": "echo hello vue3"
  }
}

shell 复制代码

# 终端执行验证
npm run hello
# 输出：hello vue3

npm list vue
# 输出：vue3-learn-demo@0.0.0 D:/projects/vue3-learn-demo
#      └── vue@3.5.x

1.3 运行与打包命令

【知识点讲解】

三条命令贯穿整个开发生涯：

npm run dev：开发模式。启动本地服务器，改代码热更新 （浏览器不用手动刷新），代码不压缩，只在本机跑。
npm run build：生产打包。把项目编译、压缩、优化，输出到 dist 目录。交给运维部署到服务器后，用户访问的就是这些文件。
npm run preview：本地模拟生产环境预览 dist，用于上线前自查打包结果是否正常。

一个常见新手坑：dev 环境一切正常，build 后白屏------通常是路径或环境变量问题，第 7、10 章会讲怎么规避。

【示例代码】

arduino 复制代码

# 开发：日常写代码时一直挂着这个命令
npm run dev

# 打包：上线前执行，生成 dist/ 目录
npm run build

# 本地预览打包产物（默认 http://localhost:4173）
npm run preview

打包成功后终端会输出产物体积清单：

bash 复制代码

dist/index.html                  0.46 kB │ gzip:  0.30 kB
dist/assets/index-DRfpwZIb.css   4.15 kB │ gzip:  1.27 kB
dist/assets/index-B2q3x1.js    167.42 kB │ gzip: 66.88 kB

【练习Demo】

需求：执行一次完整流程：dev 启动 → build 打包 → preview 预览，确认打包后的页面也能正常显示 1.1 练习中的标题。

参考实现：

arduino 复制代码

npm run dev      # 看到"我的第一个 Vue3 项目"后 Ctrl+C 停止
npm run build    # 生成 dist 目录
npm run preview  # 打开 http://localhost:4173，页面显示正常即通过

1.4 安装 vue-router、pinia 与 src 目录规划

【知识点讲解】

两个必装官方生态库：

vue-router@4：路由。单页应用（SPA）中"切换页面"的能力，URL 变化 → 显示不同组件，页面不整体刷新。
pinia：状态管理。跨页面、跨组件共享数据（如登录用户信息），是 Vue3 官方指定替代 Vuex 的方案。

企业项目的 src 目录是按职责划分的，全世界前端团队基本一致：

目录	职责	举例
`assets/`	静态资源：图片、全局样式	`assets/logo.png`、`assets/main.css`
`components/`	可复用功能组件，与路由无关	`components/SearchBar.vue`
`views/`	页面级组件，与路由一一对应	`views/LoginView.vue`
`router/`	路由配置集中地	`router/index.js`
`store/`	Pinia 状态仓库，一个业务一个文件	`store/user.js`
`utils/`	纯 JS 工具函数，不含界面	`utils/request.js`、`utils/format.js`

命名规范：组件文件大驼峰 （UserCard.vue），工具文件小驼峰 （format.js）。

【示例代码】

perl 复制代码

# 安装路由与状态管理（在项目根目录执行）
npm install vue-router@4 pinia

csharp 复制代码

# 手动创建后的完整目录结构
vue3-learn-demo/
├── public/
├── src/
│   ├── assets/
│   │   └── main.css        # 全局样式
│   ├── components/          # 公共组件
│   ├── views/               # 页面组件
│   │   └── HomeView.vue
│   ├── router/
│   │   └── index.js         # 路由配置
│   ├── store/               # Pinia 仓库
│   ├── utils/               # 工具函数
│   ├── App.vue
│   └── main.js
├── index.html
├── package.json
└── vite.config.js

javascript 复制代码

// 文件：src/main.js（入口：装配 pinia 和 router）
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'
import './assets/main.css'

const app = createApp(App)

app.use(createPinia()) // 先装 pinia：路由守卫里可能用到 store
app.use(router)        // 再装路由

app.mount('#app')

javascript 复制代码

// 文件：src/router/index.js（最小可用的路由配置）
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  // history 模式：URL 没有 #，企业项目标配
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      // 路由懒加载：访问到该页面才加载代码，优化首屏
      component: () => import('@/views/HomeView.vue')
    }
  ]
})

export default router

xml 复制代码

<script setup>
</script>

<template>
  <router-view />
</template>

xml 复制代码

<script setup>
</script>

<template>
  <div class="page">
    <h2>首页</h2>
    <p>项目骨架搭建完成，后面所有章节都在这个结构里写代码。</p>
  </div>
</template>

css 复制代码

/* 文件：src/assets/main.css（全局基础样式） */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: 'Helvetica Neue', Arial, 'PingFang SC', 'Microsoft YaHei', sans-serif;
  color: #333;
}

【练习Demo】

需求：完成依赖安装与目录规划，新增一个"关于我们"页面 /about，点击首页的链接跳转过去。

参考实现：

xml 复制代码

<script setup>
</script>

<template>
  <div class="page">
    <h2>关于我们</h2>
    <p>vue3-learn-demo 学习项目</p>
  </div>
</template>

javascript 复制代码

// 文件：src/router/index.js（在 routes 数组里追加一条）
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    { path: '/', name: 'home', component: () => import('@/views/HomeView.vue') },
    { path: '/about', name: 'about', component: () => import('@/views/AboutView.vue') }
  ]
})

export default router

xml 复制代码

<script setup>
</script>

<template>
  <div class="page">
    <h2>首页</h2>
    
    <router-link to="/about">去关于页</router-link>
  </div>
</template>

第 1 章小结

企业开发第一步永远是脚手架创建工程，npm create vite@latest 项目名 -- --template vue
npm run dev 开发、npm run build 打包、npm run preview 预览产物
node_modules 和锁文件的关系：前者不提交 git，后者必须提交
src 六大目录各司其职：assets 静态资源、components 复用组件、views 页面、router 路由、store 状态、utils 工具
vue-router 与 pinia 在 main.js 中通过 app.use() 装配，先 pinia 后 router

企业踩坑实录

这些坑来自真实团队的一线反馈，遇到同样报错时先翻这里：

npm create vite 卡在交互选择 / 模板选错 （选成了 TypeScript 或 React 模板）：最省事的办法是删掉整个目录，用带 -- --template vue 的完整命令一步到位重建，别手动改文件"抢救"。
启动时提示 Port 5173 is in use：这不是报错。Vite 会自动换用 5174、5175 等端口，以终端实际打印的地址为准，别误以为项目坏了。
同事克隆项目后跑不起来 ：九成是没执行 npm install。团队铁律：node_modules 永远不进 git（脚手架自带的 .gitignore 已帮你排除），任何人拿到代码第一件事就是装依赖。
公司内网安装依赖特别慢 ：执行 npm config set registry https://registry.npmmirror.com 切换国内镜像源，装完再切回官方源即可。

思考题（先自己答，再对照参考答案）

Q1：dependencies 和 devDependencies 有什么区别？为什么 vite 装在 dev 里，vue 装在 prod 里？

参考答案：dependencies 是运行时需要的包（vue、vue-router------打包后的代码仍在使用它们）；devDependencies 只在开发和构建阶段需要（vite、eslint------打包完成后就不再用）。放错位置一般不影响运行，但会破坏语义，也会影响某些按依赖做剪裁的场景。

Q2：npm run dev 和 npm run build 的产物有什么区别？

参考答案：dev 不产出文件，它启动一个开发服务器，浏览器请求哪个模块就实时编译哪个，所以改代码能秒级热更新；build 用 Rollup 把整个项目打包成 dist/ 目录下的静态文件，体积更小、去掉了调试信息，专门用于部署上线。

Q3：为什么 components 和 views 要分开放？

参考答案：views 与路由一一对应，是"页面级"组件；components 是可被多个页面复用的"功能级"组件。分开存放能明确改动影响面：改 views 只影响一个页面，改 components 可能影响所有引用它的页面，需要更谨慎地回归测试。

Q4：误删 node_modules 后项目还能恢复吗？

参考答案：能。package.json 和锁文件记录了全部依赖信息，重新执行 npm install 即可完整还原------这也正是它不进版本库的原因。

面试高频

问：Vite 为什么比 Webpack 快？

答：开发环境下 Vite 不做整包打包，而是利用浏览器原生 ES Module，页面用到哪个模块就向 dev server 实时请求哪个，按需编译------所以冷启动和热更新都快；生产环境才切换为 Rollup 完整打包。

问：SPA 项目为什么只有一个 index.html？

答：单页应用的所有"页面"都是 JS 动态渲染的组件，index.html 只是唯一的外壳与挂载点，切换页面实际是 JS 替换组件，不发起新的 HTML 请求。