面向:会一点 Vue2 语法、但不了解整体架构的同学 目标:从"会写组件"到"能独立搭建、配置、启动、打包一个完整生产级 Vue2 项目" 主线:以 Vue CLI(webpack) 为主,贯穿对比纯手写 webpack 项目,让你既会用脚手架,也看得懂底层
目录
- 第 0 章 先建立全局认知:一个 Vue2 项目到底由什么组成
- 第 1 章 前置知识:现代前端工程化的地基
- 第 2 章 两种项目形态:Vue CLI vs 手写 webpack
- 第 3 章 用 Vue CLI 创建第一个项目
- 第 4 章 项目目录逐文件拆解
- 第 5 章 配置文件详解:vue.config.js 与环境变量
- 第 6 章 webpack 在 Vue 项目里到底做了什么
- 第 7 章 启动流程:npm run serve 发生了什么
- 第 8 章 Vue Router:页面是怎么切换的
- 第 9 章 Vuex:全局状态怎么管
- 第 10 章 Axios:前后端数据交互
- 第 11 章 UI 组件库:以 Element UI 为例
- 第 12 章 代码规范:ESLint + Prettier
- 第 13 章 打包:npm run build 与产物分析
- 第 14 章 打包优化实战
- 第 15 章 部署上线
- 第 16 章 从零手写 webpack 配置(进阶对比)
- 第 17 章 一条完整的开发闭环(总结)
- 附录 A 常用命令速查
- 附录 B 常见坑与排查
第 0 章 先建立全局认知
在敲任何命令之前,先在脑子里建立一张"地图"。很多人学 Vue 卡住,不是因为语法不会,而是不知道每个文件、每个工具在整个项目里扮演什么角色、彼此怎么配合。
0.1 你写的 Vue 代码,浏览器看不懂
浏览器只认识三样东西:HTML、CSS、JavaScript。而你写的是 .vue 单文件组件,长这样:
<template>
<div class="hello">{{ msg }}</div>
</template>
<script>
export default {
data() {
return { msg: 'Hello Vue' }
}
}
</script>
<style scoped>
.hello { color: red; }
</style>
这种文件浏览器根本无法直接运行。它需要一整套"翻译 + 打包"的加工流程,把这个 .vue 文件:
<template>→ 编译成渲染函数(JS)<script>→ 处理成浏览器能跑的 JS<style>→ 抽出来变成真正的 CSS- 把你项目里成百上千个这样的文件,合并、压缩、优化成几个
.js和.css文件
干这套活的核心工具,就是 webpack(构建工具)。
必须先分清一件事:翻译和打包不是同一个东西。
- webpack 本体只负责打包:它顺着
import把模块串成一张"依赖图",再合并成少数几个文件。- 翻译(编译)是 loader 干的:webpack 原生只看得懂
.js和.json,遇到.vue、.scss、新语法一律不认识,必须交给对应的 loader 加工(.vue交给vue-loader、新语法交给babel-loader、.scss交给sass-loader)。一句话:webpack 是流水线,loader 是流水线上的工人。 后面第 6 章会把这套分工彻底讲透。
0.2 一张图看懂整个链路
你写的代码 构建工具(webpack) 浏览器
───────────── ────────────────── ──────────
.vue 单文件组件 ─┐
.js 业务逻辑 ─┤
.css/less 样式 ─┼──► [vue-loader / babel / css-loader] ──► app.js
图片/字体等资源 ─┤ 编译 · 转换 · 合并 · 压缩 app.css
.jpg .png .svg ─┘ index.html
▲
vue.config.js 就是
在这里面"下指令"的地方
核心结论:所谓"前端工程化",就是围绕 webpack 这条流水线,配置各种"加工规则"(loader)和"增强插件"(plugin),把你的源码变成生产可用的静态文件。Vue CLI 的本质,就是帮你把这套复杂的 webpack 配置预先封装好了。
0.3 开发态 vs 生产态:两套完全不同的目标
| 维度 | 开发环境(npm run serve) | 生产环境(npm run build) |
|---|---|---|
| 目的 | 让你写得爽、改得快 | 让用户加载快、跑得稳 |
| 是否打包到磁盘 | 否,放在内存里 | 是,输出到 dist/ 目录 |
| 代码压缩 | 不压缩,保留可读 | 高度压缩、混淆 |
| 热更新 HMR | 有,改代码秒级刷新 | 无 |
| Source Map | 完整,方便调试 | 建议关闭或精简(⚠️ CLI 5 默认 productionSourceMap: true,会生成 .map,见 5.1 / 14.4) |
| 体积 | 大 | 尽可能小 |
| 是否含调试信息 | 含 Vue 警告、devtools | 全部剔除 |
记住这个区别,后面第 7 章和第 13 章会分别展开。
第 1 章 前置知识:现代前端工程化的地基
在创建项目前,必须理解几个绕不开的基础概念。不懂这些,后面的命令和配置文件对你就是"天书"。
1.1 Node.js 与 npm:一切的起点
- Node.js:让 JavaScript 能脱离浏览器、在电脑上运行的"运行环境"。前端的构建工具(webpack、Vue CLI)本身都是用 Node 写的程序,所以必须先装 Node。
- npm:Node 自带的包管理工具(安装 Node 时会自动带上)。它的作用是从远程仓库下载别人写好的代码库(叫"包/package")到你项目里。
类比:Node.js 是"厨房",npm 是"采购员",各种开源库是"食材"。
验证安装(终端执行):
node -v # 例如 v16.20.2
npm -v # 例如 8.19.4
版本建议:Vue2 + Vue CLI 5 项目推荐 Node 14 / 16(LTS 版本)。真正会踩 OpenSSL 坑的是仍在用 webpack 4 的老项目:Node 17+ 自带的 OpenSSL 3 移除了 md4 摘要算法,启动 / 构建时会报
error:0308010C(CLI 5 用的 webpack 5 不受影响);此外 Node 18+ 装老node-sass也常因缺少预编译二进制而失败。解法见附录 B。
1.2 package.json:项目的"身份证 + 说明书"
每个前端项目根目录都有一个 package.json,它记录三件关键事:
{
"name": "my-vue-project",
"version": "1.0.0",
"scripts": {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"lint": "vue-cli-service lint"
},
"dependencies": {
"vue": "2.6.14",
"vue-router": "^3.5.4",
"vuex": "^3.6.2",
"axios": "^0.27.2",
"element-ui": "^2.15.13"
},
"devDependencies": {
"@vue/cli-service": "~5.0.8",
"vue-template-compiler": "2.6.14",
"sass": "^1.32.0",
"sass-loader": "^12.6.0"
}
}
⚠️ 别把带
//的"注释版 JSON"复制进项目:package.json是标准 JSON,不允许写注释,老教程里的// CLI 5 起用...会让npm install直接报 JSON 解析错误。说明挪到这里:
- CLI 5 起 scss 编译器用 dart-sass,包名就是
sass;sass-loader对应 12.x(CLI 4 及更早是 10.x)。vue与vue-template-compiler必须锁成完全相同的精确版本(这里都是2.6.14,不带^)。若写成^2.6.14,npm 可能把 vue 解析到 2.7.x、compiler 留在 2.6.x,编译时直接报Vue packages version mismatch(附录 B / 16.2 有解法)。
三个重点:
| 字段 | 含义 | 你什么时候关心它 |
|---|---|---|
scripts | 定义 npm run xxx 的快捷命令 | 启动、打包、检查代码都靠它 |
dependencies | 运行时依赖,线上也要用(vue、router、axios) | 装库时判断放哪 |
devDependencies | 开发时依赖,只在打包前用(构建工具、loader、sass) | 装库时判断放哪 |
dependencies和devDependencies怎么区分? 一句话:打包后的线上代码里还需要的,放dependencies(如 vue、axios);只是帮你把代码构建出来的工具,放devDependencies(如 sass-loader、@vue/cli-service)。
node-sass和sass是什么关系? 老教程里常见node-sass,它是早年 CLI(4 及更早)默认的 scss 编译器,对 Node 版本极其敏感(Node 16 以上基本装不上)。Vue CLI 5 起换成sass(也就是 dart-sass),纯 JS 实现、不挑 Node 版本,所以本文档从头到尾都用sass。附录 B 里那条 node-sass 报错就是这个历史包袱。
1.3 版本号里的符号:^ 和 ~
^2.6.14:允许升级 小版本和补丁(可升到 2.7.x,但不升 3.x)~5.0.8:只允许升级 补丁版本(可升到 5.0.9,不升 5.1.0)- 无符号
2.6.14:锁死这个版本
1.4 package-lock.json 与 node_modules
node_modules/:所有下载的依赖包实际存放的目录,体积巨大,绝不提交到 git。package-lock.json:锁定每个依赖的精确版本和下载地址,保证你同事、服务器装出来的依赖和你一模一样。必须提交到 git。
所以拿到一个别人的项目,第一步永远是:
npm install # 按 package.json + lock 文件,把 node_modules 装齐
1.5 模块化:import / export
Vue 项目里随处可见 import xxx from 'xxx',这是 ES Module(ESM) 规范——2015 年写进 JS 语言标准的官方模块化方案。webpack 的一大核心能力就是把这些 import 依赖关系静态分析出来,串成一张依赖图,再打包。你不用背规范全文,但必须能把下面这套写法认全、用对,因为 .vue 文件、路由、Vuex、组件拆分,底层全是它。
1.5.1 为什么非要模块化
早期 JS 没有模块,多个 <script> 靠全局变量通信,三个致命问题:
- 全局污染:所有人往
window上挂东西,名字一撞就互相覆盖 - 依赖靠人肉排序:A 依赖 B,你就得保证 B 的
<script>写在 A 前面,项目一大根本理不清 - 无法按需加载:要么全加载,要么不加载
ESM 的解法:每个文件就是一个独立模块,有自己的作用域。文件里定义的变量默认外部看不见,想给外面用必须显式 export;想用别人的必须显式 import。依赖关系由代码本身声明,而不是靠约定和顺序。
1.5.2 export:把东西交出去
两种导出方式,这是整章最容易混的点。
① 默认导出(default export)—— 一个文件只能有一个
// utils/format.js
export default function formatDate(date) {
return date.toLocaleDateString()
}
"默认"的含义是:这个文件主推的就是它,导入方可以随便起名。
import formatDate from './utils/format' // 叫 formatDate 行
import fmt from './utils/format' // 叫 fmt 也行,反正拿到的都是那个默认导出
Vue 单文件组件 export default { ... } 导出的就是组件选项对象,所以你导入组件时名字自己定:
import MyComp from './components/MyComp.vue'
import HelloWorld from './components/HelloWorld.vue'
.vue文件里必须用export default导出组件对象,这是 vue-loader 的硬性约定,不能改成具名导出。
② 具名导出(named export)—— 一个文件可以有任意多个
// utils/helpers.js
export const PI = 3.14159
export function add(a, b) { return a + b }
export function sub(a, b) { return a - b }
// 也可以先定义、最后统一导出(更常见,导出清单一目了然)
// ⚠️ 上面那种"逐个 export"和下面这种"统一 export"是【两种写法,任选其一】,
// 别把两份都抄进同一个文件:同一个【导出名】出现两次会报
// SyntaxError: Duplicate export of 'PI'(是"重复导出",不是"重复声明")。
// 但"同一个变量换不同名字导出多次"是合法的,例如
// export { PI as PI_VALUE } —— 只是多开一个别名,见 1.5.7。
const PI = 3.14159
function add(a, b) { return a + b }
function sub(a, b) { return a - b }
export { PI, add, sub }
导入时名字必须严格对上,且要加花括号:
import { add, sub } from './utils/helpers' // ✅ 名字必须和导出时一致
import { add as sum } from './utils/helpers' // 用 as 起别名,避免和本地变量重名
import { add, PI } from './utils/helpers' // 一次导入多个
1.5.3 import:把东西拿进来
把导入写法补齐,你会在真实项目里全部遇到:
// ① 导入默认导出(无花括号)
import Vue from 'vue'
// ② 导入具名导出(有花括号)
import { mapState, mapGetters } from 'vuex'
// ③ "默认 + 具名"混合导入确实存在,但前提是【对方真的提供具名导出】。
// ⚠️ Vue 2.6 的 'vue' 包只有默认导出,下面这行在 Vue 2.6 里会直接报
// "does not provide an export named 'nextTick'":
// import Vue, { nextTick } from 'vue' // ❌ 别在 Vue 2.6 项目里这么写
Vue.nextTick(() => { /* ... */ }) // ✅ Vue 2.6 的正确写法(Vue 已在 ① 导入)
// (Vue 2.7 起 ESM 构建才把 nextTick / set / del 导出为具名 API;
// Vue 3 则全面改成 import { nextTick } from 'vue'。)
// 真正能演示混合导入的,是自己写的文件:
import Calc, { add } from './math' // ✅ 默认 + 具名
// ④ 整体导入:把整个模块的所有导出收成一个命名空间对象
import * as helpers from './utils/helpers'
helpers.add(1, 2) // ✅ 具名导出挂在 helpers 上
// ⚠️ helpers.js 只有具名导出,helpers.default 是 undefined,不能当函数调用。
// 想拿 .default,得导入一个【有默认导出】的模块,例如 1.5.2 的 format.js:
import * as fmt from './utils/format'
fmt.default(new Date()) // ✅ default 就是那个 formatDate 函数
// ⑤ 只导入副作用,不接收任何东西(执行这个模块,但不要它的导出)
import './styles/global.scss' // 在 main.js 里你见过
import 'element-ui/lib/theme-chalk/index.css'
// ⑥ 动态导入:返回一个 Promise,是路由懒加载的底层机制
import('@/views/About.vue').then(module => module.default)
const About = () => import('@/views/About.vue') // 第 8 章的懒加载就是这行
// (Vue Router 会自动取 Promise 里的组件对象)
一张表记住核心区别:
| 默认导出 | 具名导出 | |
|---|---|---|
| 数量 | 一个文件只能 1 个 | 一个文件任意多个 |
| 导出写法 | export default X | export const X / export { X } |
| 导入写法 | import X from '...'(无花括号) | import { X } from '...'(有花括号) |
| 导入名 | 随便起 | 必须一致,可用 as 改 |
| 典型用途 | 一个 .vue 组件、一个主类 | 工具函数集合、Vuex 的 mapXxx 辅助函数 |
最常见的报错
SyntaxError: ... does not provide an export named 'xxx':九成是花括号用错了——把默认导出当具名导入了,或反过来。看到它先去对一眼对方文件是export default还是export。
1.5.4 路径怎么写:三种写法与 resolve 规则
import A from './components/A.vue' // ① 相对路径:必须以 ./ 或 ../ 开头,相对当前文件
import B from '@/utils/b' // ② 别名路径:@ 是 CLI 预设的 src 目录别名(第 16 章会看到它的 webpack 配置)
import Vue from 'vue' // ③ 裸模块名:不带路径符号,去 node_modules 里找
几条必须知道的规则:
- 不写
./开头会被当成第三方包。import utils from 'utils'会去node_modules找,找不到就报错——这是新手高频坑。 - 后缀可省略(webpack 项目里)。webpack 5 自身默认按
['.js', '.json', '.wasm']补全;Vue CLI 5 在此基础上把.vue、.jsx、.mjs也加了进去(大致['.mjs', '.js', '.jsx', '.vue', '.json', '.wasm']),所以./a能命中a.js或a.vue。顺序靠前的优先,同一目录下同名不同后缀(a.js和a.vue并存)时省后缀会拿到你意想不到的那个,组件一律带上.vue。手写 webpack 项目没有这些预设,得自己配(16.3 节就是['.js', '.vue', '.json'])。 - 目录会找
index。import x from './components'会按resolve.extensions的顺序去找./components/index.js、index.vue…,通常等价于./components/index.js。 @别名的真相:它不是 JS 语法,是 webpackresolve.alias配出来的('@': src)。换到手写 webpack 项目里默认没有,得自己配(第 16.3 节)。
1.5.5 ESM 的三个特性(决定了它的行为)
① 静态:import 必须在文件顶层,不能被 if 包住,路径不能是变量。
if (true) { import a from './a' } // ❌ 语法错误
const p = './a'; import a from p // ❌ 语法错误
正因为"静态",webpack 不用运行代码就能分析出依赖关系,这是能做 tree-shaking(摇掉没用到的导出)的前提。要动态加载就用 import() 函数(写法 ⑥)。
② 被 import 的模块会"先跑完",且导入绑定只读
import { x } from './m'
console.log(x) // ✅ 正常,m 模块已经执行完,x 有值
x = 1 // ❌ 报错,导入的是"只读绑定",不能赋值
别把这个理解成"变量提升"。准确机制是:ESM 会先对当前模块所依赖的那条链上的模块求值(执行)完,再执行当前模块自身的代码,所以
./m一定比你先跑完。注意不是"整张依赖图所有模块"——存在循环依赖时求值顺序会更绕,但"依赖先于使用者"这条不变。这不是var那种提升,而是模块求值顺序。另外:虽然把
console.log(x)写在import前面也能跑(import 声明会被提升),但 ESLint 的import/first规则会直接报错,实际项目里一律把 import 写在文件最顶部。
③ 模块只执行一次:同一个模块被十个文件 import,代码只跑一遍,导出的是同一个对象引用。这一点极其重要——它正是 Vuex 能做到"全局唯一 store"的底层原因:store/index.js 里 export default new Vuex.Store(),谁 import 谁拿到同一个实例。
1.5.6 Vite 时代的一个坑(提前埋个雷)
Vue CLI 用的是 webpack,而 Vite 用浏览器原生 ESM + 依赖预构建。
⚠️ 别把原因记成"不认裸模块名":Vite 会把
vue、axios这类裸模块名预构建成 ESM,所以import Vue from 'vue'在 Vite 里照样能用。真正的坑是省略扩展名——Vite 的resolve.extensions默认不含.vue,官方文档也明确要求导入单文件组件时写全.vue后缀。
import Vue from 'vue' // ✅ 裸模块名由 Vite 预构建处理,没问题
import A from './components/A.vue' // ✅ 写全扩展名
// import A2 from './components/A' // ❌ 解析不到 .vue,开发/构建都可能报错(也别和上面的 A 同名)
后面你要学 Vite 时(第 16 章对比),碰到"CLI 里好好的、Vite 里报错"的导入问题,回来看这一条。
1.5.7 一页速记
// ▼ 导出方:math.js
export const PI = 3.14 // 具名,可多个
export function add(a, b) { return a + b }
export default class Calculator {} // 默认,仅一个
export { PI as PI_VALUE } // 同一个变量换个名字再导出,合法(不是重复导出)
// ▼ 导入方(写在支持 ESM 的模块里)
import Calc, { add, PI as PI2 } from './math' // 默认 + 具名 + 别名,一次拿全
import * as math from './math' // 整体收拢成命名空间对象:math.add / math.default
import './styles/global.scss' // 只要副作用(样式才是典型场景,纯函数模块没意义)
// 动态导入返回 Promise:要么 .then,要么放进 async 函数里 await
import('./math').then(m => { console.log(m.default, m.add(1, 2)) })
async function lazyLoad() {
const m = await import('./math') // ✅ 在 async 函数里 await 才稳妥
return m.default
}
// ⚠️ 别直接在模块顶层写 `const m = await import(...)`:顶层 await 需要构建工具
// 显式开启(webpack 5 的 experiments.topLevelAwait),Vue CLI 5 默认没开。
// 路由懒加载常用的是这一行:
const About = () => import('@/views/About.vue')
判断口诀:看到花括号 → 对方是具名导出;没花括号 → 对方是默认导出。这个规律在 Vue 项目里 99% 的场景成立。
剩下的 1%:
import * as X from '...'(整体导入,收成命名空间对象,不是某个具名导出)、import './xxx.css'(副作用导入,没有花括号,但也不是默认导出)。
第 2 章 两种项目形态:Vue CLI vs 手写 webpack
你选择了"两者都对比",这一章就是总纲。市面上 95% 的 Vue2 项目属于第一种,但理解第二种能让你彻底看透第一种。
2.1 形态一:Vue CLI 脚手架项目(主流,你要主要掌握的)
它是什么:官方出的命令行工具,一条命令生成一个配好 webpack 的完整项目骨架。webpack 配置被封装在 @vue/cli-service 里,你平时看不到、也不用改,只通过一个 vue.config.js 做少量覆盖。
优点:开箱即用、零配置起步、社区标准、教程最多、踩坑资料最全。 适合:绝大多数业务项目,也是你找工作、接手公司项目会遇到形态。
2.2 形态二:纯手写 webpack 项目(底层,用来理解原理)
它是什么:不借助脚手架,自己从零写 webpack.config.js,一个 loader 一个 plugin 手动配。
优点:完全可控、能学到本质、可做高度定制。 缺点:配置繁琐、版本坑多、维护成本高。 适合:学习原理、特殊定制需求、或维护一些历史老项目。
2.3 一张表看懂两者关系
| 对比项 | Vue CLI 项目 | 手写 webpack 项目 |
|---|---|---|
| webpack 配置在哪 | 藏在 node_modules/@vue/cli-service 里,你只写 vue.config.js 覆盖 | 项目根目录的 webpack.config.js,全部自己写 |
| 起步成本 | 一条命令,2 分钟 | 手动装十几个包、写几百行配置 |
| 需要懂 webpack 吗 | 会用即可,不懂也能开发 | 必须懂,否则配不动 |
| 本质 | 也是 webpack,只是被封装了 | 裸的 webpack |
| 适用项目占比(经验值) | 约 95% | 约 5% |
关键认知:Vue CLI 不是另一个构建工具,它就是 webpack + 一堆预设配置。你学会 Vue CLI 后再看手写配置,会发现"哦,原来 CLI 帮我干的活就是这些"。这也是本文档第 16 章要带你手写的意义——把 CLI 的黑盒打开给你看。
第 3 章 用 Vue CLI 创建第一个项目
动手环节。跟着做一遍,比看十遍都管用。
3.1 安装 Vue CLI(只需装一次,全局)
npm install -g @vue/cli
验证:
vue --version # 能看到版本号(如 @vue/cli 5.0.8)就成功了
如果报
vue 不是内部或外部命令,是 npm 全局路径没配进环境变量,搜索"npm 全局安装路径配置 PATH"解决即可。
3.2 创建项目
vue create my-vue-project
回车后会进入交互界面,关键选择如下:
第一步:选预设
? Please pick a preset:
Default ([Vue 2] babel, eslint) ← 简单预设,够用但不全
Default (Vue 3) (...)
❯ Manually select features ← 选这个!手动挑选,学到最多
第二步:选功能(用空格勾选,回车确认)
❯◉ Babel ← 必选,让新 JS 语法能在旧浏览器跑
◯ TypeScript ← 暂不选
◉ Router ← 选,页面路由
◉ Vuex ← 选,状态管理
◉ CSS Pre-processors ← 选,用 Sass/Less
◉ Linter / Formatter ← 选,代码规范
◯ Unit Testing ← 暂不选
◯ E2E Testing ← 暂不选
第三步:逐个确认细节
? Choose Vue version: 2.x ← 关键!一定选 2.x
? Use history mode for router? Yes ← 路由用 history 模式(后文讲)
? Pick a CSS pre-processor: Sass/SCSS (with dart-sass) ← 推荐 dart-sass
? Pick a linter config: Standard config ← 或 Prettier,见第12章
? Pick additional lint features: Lint on save ← 保存时自动检查
? Where do you prefer placing config: In dedicated config files ← 配置独立成文件,更清晰
? Save this as a preset for future projects? No
不同 CLI 版本的提问顺序和措辞有差异,认关键字就行,别死记上面的字。 常见差异:CLI 4 会在一开始就问
Choose a version of Vue.js,CLI 5 改成选完 Manually 之后再问Choose Vue version;linter 选项名有的版本叫ESLint + Standard config,有的只叫Standard config。只要认准"选 2.x"这一项,其他按自己需要勾。
3.3 等待安装完成后
cd my-vue-project # 进入项目
npm run serve # 启动开发服务器
终端会输出类似:
App running at:
- Local: http://localhost:8080/
- Network: http://192.168.1.100:8080/
浏览器打开 http://localhost:8080,看到 Vue 欢迎页就成功了。🎉
恭喜,你已经完成了"创建 → 启动"两个核心环节。 接下来我们要搞懂这套东西到底装了什么、为什么能跑起来。
第 4 章 项目目录逐文件拆解
生成的项目长这样。这一章把每个文件的作用讲清楚,这是"看懂项目"的基本功。
my-vue-project/
├── node_modules/ # 所有依赖包(npm install 装的,不提交 git)
├── public/ # 无需构建、原样拷贝的资源
│ ├── favicon.ico # 网站小图标
│ └── index.html # 唯一的 HTML 模板(应用的"壳")
├── src/ # ★ 你的所有源码都在这里
│ ├── assets/ # 会被 webpack 处理的静态资源(图片、全局样式)
│ ├── components/ # 公共/通用组件
│ ├── views/ # 页面级组件(配合路由使用)
│ ├── router/ # 路由配置
│ │ └── index.js
│ ├── store/ # Vuex 状态管理
│ │ └── index.js
│ ├── App.vue # 根组件(所有页面的"外壳")
│ └── main.js # ★ 整个应用的入口文件
├── .gitignore # git 忽略规则(node_modules、dist 等)
├── .eslintrc.js # ESLint 代码规范配置
├── babel.config.js # Babel 配置(JS 语法降级)
├── vue.config.js # ★ webpack 的覆盖配置(默认没有,需要自己建)
├── package.json # ★ 项目身份证:依赖、脚本
├── package-lock.json # 依赖精确版本锁
└── README.md # 项目说明
4.1 三个"必背"入口文件
整个应用的启动链条是:index.html → main.js → App.vue。搞懂这三个,就搞懂了 Vue 项目怎么"活"起来。
① public/index.html —— 应用的壳
<!DOCTYPE html>
<html lang="">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
<title><%= htmlWebpackPlugin.options.title %></title>
</head>
<body>
<noscript>需要启用 JavaScript 才能运行本应用</noscript>
<div id="app"></div> <!-- ★ 关键:Vue 会把整个应用挂载到这个 div 里 -->
</body>
</html>
注意 <div id="app"></div>——这是整个应用的挂载点,Vue 生成的所有界面最终都塞进这个空 div。<%= ... %> 是模板语法,构建时会被替换成真实值。
② src/main.js —— JS 入口
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'
Vue.config.productionTip = false // 关掉生产提示(⚠️ 仅 Vue 2 有这个选项,Vue 3 里无效)
new Vue({
router, // 注入路由
store, // 注入状态管理
render: h => h(App) // 渲染根组件 App
}).$mount('#app') // ★ 挂载到 index.html 的 #app 上
这是整个应用的"总开关":创建 Vue 根实例,把 router、store 装进去,渲染 App 组件,最后挂到页面上。$mount('#app') 就是和 index.html 那个 <div id="app"> 对上的地方。
③ src/App.vue —— 根组件
<template>
<div id="app">
<div id="nav">
<router-link to="/">Home</router-link> |
<router-link to="/about">About</router-link>
</div>
<router-view/> <!-- ★ 路由匹配的页面组件会渲染在这里 -->
</div>
</template>
<router-view> 是个占位符:URL 变了,这里就换成对应的页面组件。这就是"单页应用(SPA)"的核心——页面永不刷新,只换 <router-view> 里的内容。
4.2 public 和 assets 的区别(高频考点)
| 目录 | 是否经过 webpack 处理 | 引用方式 | 适用场景 |
|---|---|---|---|
public/ | ❌ 不处理,原样拷贝到 dist 根目录 | 必须用绝对路径 /xxx.png 或 <%= BASE_URL %> | 文件名不能变、需固定路径的(如 favicon、第三方库) |
src/assets/ | ✅ 处理:压缩、加 hash、小于 8KiB 内联为 base64(CLI 5 默认,见 14.5) | 相对路径 import 或 require | 绝大多数图片、样式 |
经验法则:能放
assets就放assets,享受 webpack 的优化(加 hash 防缓存、压缩体积);只有确实需要固定文件名的才放public。
第 5 章 配置文件详解:vue.config.js 与环境变量
这是"会配项目"的核心技能。默认项目没有 vue.config.js,需要你在根目录手动创建。
5.1 vue.config.js 基本结构
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
publicPath: '/', // 部署的基础路径
outputDir: 'dist', // 打包输出目录
assetsDir: 'static', // 静态资源子目录,打包后是 dist/static/css、dist/static/js…
// ESLint 检查时机。⚠️ CLI 5 默认值是 'default'(等价于 true):
// 一个 ESLint error 就会让开发服务器编译失败、浏览器弹出错误遮罩。
// 'warning' = 只提示不阻断;false = 完全关闭。
lintOnSave: 'warning',
productionSourceMap: false, // 生产环境不生成 source map(加速打包、隐藏源码)
// 开发服务器配置
devServer: {
port: 8080, // 端口
open: true, // 启动后自动打开浏览器
proxy: { // ★ 代理,解决开发时的跨域(第10章详讲)
'/api': {
target: 'http://localhost:3000',
changeOrigin: true,
pathRewrite: { '^/api': '' }
}
}
},
// 链式修改内部 webpack 配置(进阶,第14章用)
chainWebpack: (config) => {
// 这里可以精细改 webpack
}
})
5.2 环境变量:一套代码,多套配置
这是工程化里极其重要的概念。同一个项目,开发环境和生产环境的接口地址、配置往往不同。硬编码在代码里是灾难,正确做法是用环境变量。
Vue CLI 内置了三种模式:
| 模式 | 触发命令 | 加载的文件 |
|---|---|---|
| development | npm run serve | .env + .env.development |
| production | npm run build | .env + .env.production |
| 自定义(如 test) | vue-cli-service build --mode test | .env + .env.test |
在根目录创建文件(变量必须以 VUE_APP_ 开头才会被注入):
.env.development:
VUE_APP_API_BASE=http://localhost:3000
VUE_APP_TITLE=开发环境
.env.production:
VUE_APP_API_BASE=https://api.online.com
VUE_APP_TITLE=生产环境
写法提醒:
.env由 dotenv 解析,等号两边带空格也能读,但一律写成KEY=value不带空格最稳妥——KEY = value的空格容易被误当成值的一部分,复制进 shell / CI 变量时尤其容易出错。
在代码里使用:
// 任何 .js / .vue 文件里都能读到
console.log(process.env.VUE_APP_API_BASE)
// serve 时打印 http://localhost:3000
// build 时打印 https://api.online.com
原理:webpack 打包时会用
DefinePlugin把process.env.VUE_APP_xxx文本替换成你写的具体值。所以生产包里根本没有"判断环境"的逻辑,就是写死的字符串——这也是为什么必须以VUE_APP_开头(这是 Vue CLI 约定的白名单前缀)。
两个内置变量(不用自己定义):
process.env.NODE_ENV:值为'development'或'production'process.env.BASE_URL:就是publicPath的值
第 6 章 webpack 在 Vue 项目里到底做了什么
6.0 先记住一个比喻:webpack 是一家"文件加工厂"
你项目里写的东西,浏览器大部分看不懂:
.vue文件浏览器不认识.scss浏览器不认识- 箭头函数、
?.,IE11 不认识 - 你写了 50 个文件互相
import,浏览器不会自己去一个个下载
所以需要一家工厂,把"你写的源码"加工成"浏览器能跑的少数几个文件"。webpack 就是这家工厂。
工厂有五个角色(表格虽然是五个,习惯上叫"四要素",因为"依赖图"是 webpack 顺着入口自动算出来的,不用你配):
| 角色 | 白话 | Vue 项目里 | 要不要你配 |
|---|---|---|---|
| Entry 入口 | 从哪张订单开始干活 | src/main.js | ✅ 要 |
| 依赖图 | 顺着订单把所有原料找齐 | 顺着 import 自动爬 | ❌ 自动 |
| Loader | 每种原料一台专用加工机器 | vue-loader、babel-loader… | ✅ 要 |
| Plugin | 加工之外的杂活 | 生成 html、抽离 css… | ✅ 要 |
| Output | 成品仓库 | dist/ | ✅ 要 |
6.1 四要素:把工厂角色对号入座
Entry 入口:为什么是 main.js
因为 main.js 是整个应用的起点:
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'
new Vue({ router, store, render: h => h(App) }).$mount('#app')
webpack 从这一行行 import 开始,像查户口一样往下追:App.vue 里又 import 了谁、router 里又 import 了哪些页面……追完为止。
入口不是"最重要的文件",而是"依赖的起点"。你换个入口,webpack 就换一条线爬。
Output:dist/js/app.[hash].js 是什么
打包完,工厂出货,放在 dist/:
dist/
├── index.html ← 自动注入了 <script> / <link> 的入口页
└── static/ ← 只有显式配了 assetsDir: 'static'(见 5.1)才有这一层
├── js/
│ ├── app.3f2a1b.js ← 你自己的业务代码
│ └── chunk-vendors.9c8b7d.js ← node_modules 里的第三方库(同样带 hash)
└── css/
└── app.8c9d0e.css
⚠️
assetsDir的默认值是空字符串'',不是'assets':默认打包结果是dist/js/app.xxx.js、dist/css/app.xxx.css,没有中间那一层。只有像 5.1 那样设了assetsDir: 'static',才会多出dist/static/。另外 CLI 5 默认不会单独产出runtime.js(webpack 的 runtime 代码内联在包里),要单独拆出来得配configureWebpack: { optimization: { runtimeChunk: 'single' } }。第 13.1 节的输出示例按默认值
''展示;13.2 节的目录图沿用 5.1 的static配置,看的时候注意区分。部署时publicPath和这层目录要对得上,否则资源 404 白屏。
[hash] 那串乱码是根据文件内容算出来的指纹。内容一变,指纹就变,文件名就变。这样浏览器缓存就不会拿旧文件糊弄你——这是"发版后用户看到旧页面"问题的标准解法。
Loader:webpack 天生只认识 JS
这是最关键的一句:webpack 原生只看得懂 .js 和 .json。遇到别的后缀,它当场罢工,除非你给它配一台"翻译机"。
于是有了规则表(vue.config.js 背后其实长这样):
module.exports = {
module: {
rules: [
{ test: /\.vue$/, use: 'vue-loader' }, // .vue → 认识
{ test: /\.js$/, use: 'babel-loader' }, // 新语法 → 旧语法
{ test: /\.scss$/, use: ['style-loader', 'css-loader', 'sass-loader'] },
// ⚠️ CLI 5 = webpack 5,用内置 Asset Modules,不是 webpack 4 的 url-loader
{
test: /\.(png|jpe?g|gif|svg)$/,
type: 'asset', // 小图自动内联 base64
parser: { dataUrlCondition: { maxSize: 8 * 1024 } } // 默认 8KiB
}
]
}
}
读法:遇到 .vue 结尾的文件,交给 vue-loader 处理。就这么直白。
这份是示意(真实 CLI 配置由
chainWebpack管,见 16.4)。url-loader属于 webpack 4 时代,在 CLI 5 里照着写会装不上或不生效;阈值与改法详见 14.5。
Plugin:loader 干不了的杂活
loader 是"针对某个文件做加工",plugin 是"在整个打包流程的某个时刻插一脚"。两者最容易混,用两个例子区分:
HtmlWebpackPlugin:它不加工任何单个文件,它干的事是——打包结束后,生成一个index.html,并自动把<script src="app.xxx.js">塞进去。这是"流程级"的活,loader 干不了。DefinePlugin:它把代码里所有process.env.NODE_ENV文本替换成"production"。这也是全局行为。
一句话记:loader 管"文件进、文件出",plugin 管"流程节点上做点事"。
6.2 一个 .vue 文件的完整旅程
你写:
<template>
<div class="hello">{{ msg }}</div>
</template>
<script>
export default { data: () => ({ msg: 'hi' }) }
</script>
<style scoped lang="scss">
.hello { color: red; }
</style>
webpack 读到 import App from './App.vue',发现后缀是 .vue,查表 → 交给 vue-loader。
vue-loader 自己不会编译任何东西,它是"调度员",把这个文件拆成三块"虚拟文件":
App.vue?vue&type=template → 交给 vue-template-compiler
App.vue?vue&type=script → 当成普通 .js,交给 babel-loader
App.vue?vue&type=style → 交给 sass-loader → css-loader → style-loader
三块分别加工:
- template 块 →
vue-template-compiler把 HTML 模板编译成一个 JS 函数(render 函数)。你写的<div>{{ msg }}</div>最终变成类似_c('div', [_v(_s(msg))])的函数调用。浏览器不认模板,只认这个函数。 - script 块 → 就是普通 JS,走 babel-loader 降级。
- style 块 →
sass-loader先把 scss 编译成 css →css-loader把 css 变成能被import的 JS 模块 →style-loader在运行时把 css 塞进<style>标签(生产环境则换成MiniCssExtractPlugin抽成独立.css文件)。
最后 vue-loader 把三块结果组装成一个组件对象,大致是:
{
render: function() {...}, // 来自 template
data: () => ({ msg: 'hi' }), // 来自 script
_scopeId: 'data-v-f3f4a5' // 来自 scoped(Vue 2 内部选项名是【一个】下划线)
}
⚠️ 是
_scopeId不是__scopeId。这是 Vue 2 内部的组件选项名,由 vue-loader 注入;写错名字去 devtools 里找是找不到的。
热更新为什么能只刷新局部:因为 vue-loader 把三个块拆成了三个独立的依赖模块,改 template 只让 template 那块失效重编译,script 不动。这就是"改一个 .vue 秒刷新"的底层原因。
6.3 <style scoped> 到底做了什么
这是面试高频题,原理不难,但有三处细节必须说准,否则一被追问就露馅。
6.3.1 核心两步
你写:
<template><div class="hello">hi</div></template>
<style scoped>.hello { color: red; }</style>
第一步:给元素打上一个本组件唯一的属性(vue-loader 在编译期加的):
<div class="hello" data-v-f3f4a5>hi</div>
第二步:把 CSS 选择器改写成"属性也要匹配":
.hello[data-v-f3f4a5] { color: red; }
于是这条样式只命中"同时有 hello 类、且带 f3f4a5 属性"的元素。别的组件元素没这个属性,自然不受影响。没有黑魔法。
6.3.2 关键细节一:到底"哪些元素"会被打上属性?
不是"模板里所有元素",而是分三种情况——这一条是理解后面所有问题的钥匙:
| 元素 | 会不会带上你的 data-v-x | 原因 |
|---|---|---|
本组件模板里的原生标签(div、span…) | ✅ 会 | 由你的模板编译而来 |
模板里出现的组件标签(如 <el-input>)渲染出的根元素 | ✅ 会(而且同时带上子组件自己的 data-v-y) | 它出现在你的模板里,Vue 会把父作用域 id 一并挂上去 |
子组件内部的元素(如 .el-input__inner) | ❌ 不会带你的 data-v-x | 那是子组件自己的模板编译出来的;子组件自己写了 scoped 才带 data-v-y,像 Element UI 这类全局样式的库则一个 data-v 都没有 |
6.3.3 关键细节二:选择器改写,只改"最后一段"
不是每一段都加,而是只在最后一个复合选择器末尾追加:
.a .b → .a .b[data-v-x] /* 只加在 .b 上,不是 .a[data-v-x] .b[data-v-x] */
.a:hover → .a:hover[data-v-x]
.a > .b + .c → .a > .b + .c[data-v-x]
.a, .b → .a[data-v-x], .b[data-v-x] /* 逗号分隔的每个选择器各加一次 */
6.3.4 为什么改不动第三方组件样式
以 Element UI 的 <el-input> 为例,它渲染出来的真实 DOM 大致是:
<div class="el-input" data-v-f3f4a5> ← 根元素:带父组件的 data-v-x,直接写 .el-input 就能改
<input class="el-input__inner"> ← 内部元素:没有任何 data-v(Element UI 自己不用 scoped)
</div>
注意:根元素上那个
data-v-f3f4a5是父组件的 scoped id,不是 Element UI 自带的;Element UI 2.x 的样式是全局的,组件内部元素身上不会有任何data-v属性。
你在组件里写:
.my-input input { ... }
按 6.3.3 的规则,编译后变成:
.my-input input[data-v-f3f4a5] { ... }
它要求那个 <input> 身上带 data-v-f3f4a5——但它没有,所以匹配不上,样式静默失效(不报错,这才最坑)。
6.3.5 解法:深度选择器("穿透")
<style scoped>
/* 写法 A:裸穿透 */
::v-deep .el-input__inner { border: 1px solid red; }
/* 写法 B:带外层类名(推荐,作用范围收得住) */
.my-input ::v-deep .el-input__inner { border: 1px solid red; }
</style>
穿透的本质:把 data-v-x 从选择器末尾往前挪一格,贴到深度选择器前面那一段上,后面的部分放行不再追加。所以编译结果是:
/* 写法 A 编译为 → */ [data-v-f3f4a5] .el-input__inner
/* 写法 B 编译为 → */ .my-input[data-v-f3f4a5] .el-input__inner
两个必须知道的点:
- 作用域没有消失,只是边界前移了。写法 A 会命中本组件内任意位置的
.el-input__inner(包括你自己写的),容易误伤;所以推荐写法 B,用外层类名把范围圈住。::v-deep前面要有空格。::v-deep .el-input__inner是"后代选择器";写成.my-input::v-deep .el-input__inner(没空格)含义完全不同,会贴到.my-input上。
各版本写法对照(照着用,别混):
| 写法 | 适用 | 注意 |
|---|---|---|
>>> | 仅纯 CSS | SCSS/Less 会把它当除号/组合符,直接语法报错 |
/deep/ | Vue 2 可用 | 已废弃,新版 Dart Sass 会输出 deprecation 警告 |
::v-deep | Vue 2 通用 | Vue 2 里最稳的选择 |
:deep() | Vue 3 官方,Vue 2.7 起也支持 | Vue 3 里写 ::v-deep .foo 这种组合符形式已废弃并会警告,必须写成 :deep(.foo) |
6.3.6 三个常被追问的 scoped 副作用
v-html插入的内容不带data-v-x,所以 scoped 样式对它完全无效。解法:给v-html外层包一个普通 class,用非 scoped 的<style>块写。body/html/#app这类根级选择器会失效。因为它们被改写成body[data-v-x],而<body>上根本没有这个属性。这类全局样式请写在不带 scoped 的<style>里。- 穿透会让样式"漏"到子组件,这是既定行为不是 bug;反过来,父组件想改子组件根元素的样式是不需要穿透的(根元素本来就有父的
data-v-x)。
6.3.7 比穿透更优先的三种做法
穿透是兜底手段,优先级应该排在最后:
- 组件自带的 props / 配置项(最优选,升级组件库不会挂):
<el-input size="small" :clearable="true"></el-input>⚠️ 别把 Element Plus(Vue 3)的 CSS 变量抄进 Vue 2 项目:
--el-input-border-color这类变量是 Element Plus / Vue 3 的方案,Element UI 2.x 不支持,写了不会有任何效果。 - 非 scoped 的
<style>块 + 全局唯一类名(一定要包一层,否则污染全局):<style> .my-page-unique .el-input__inner { border-color: red; } </style> :global()(Vue 2.7 / Vue 3)::global(.el-input__inner) { ... }
6.4 Babel:一个"语法翻译官"
你写的:
const getName = (user) => user?.name ?? '匿名'
IE11 看到 =>、?.、?? 直接报错。Babel 把它翻译成老语法:
var getName = function (user) {
var _user$name;
return (_user$name = user === null || user === void 0 ? void 0 : user.name) !== null
&& _user$name !== void 0 ? _user$name : '匿名';
}
翻译到什么程度,谁说了算? 由 .browserslistrc 决定:
> 1%
last 2 versions
not dead
意思是"支持全球占有率 >1% 的浏览器"。Babel 的 preset-env 会去查这张浏览器清单,只翻译它们不认识的语法。如果清单里全是现代浏览器,很多语法原样保留,产物更小。
babel.config.js 里的 presets: ['@vue/cli-plugin-babel/preset'] 就是 Vue CLI 打包好的一套 Babel 配置(内含 preset-env + Vue 相关的 JSX 支持等),你不用自己一个个装插件。
⚠️ 一个能让你线上爆炸的误区:Babel 只转"语法",不补"API"
Babel 只会把新语法改写成旧语法(
=>、?.、??、解构、class这些)。它不会给旧浏览器补上新 API:
类别 例子 Babel 管不管 语法 ?.??箭头函数 解构classasync/await✅ 管,会转写 API Promise、Array.prototype.includes、Object.assign、flat()❌ 不管,IE11 里照样 xxx is not a function想让老浏览器用上新 API,得靠 polyfill(垫片):在
babel.config.js里配useBuiltIns: 'usage'+core-js。好消息是@vue/cli-plugin-babel已经内置了这套机制,你只要确保两件事:
.browserslistrc里真的写了要支持的老浏览器(比如ie 11);配了 IE11,CLI 才会自动注入对应的垫片。- 别把
core-js卸了,也别把 preset 换成一个裸的@babel/preset-env却忘了配useBuiltIns。结论:配了 Babel ≠ 能跑 IE11。语法能跑、API 未必有,线上白屏的最高频原因之一就是这条。
6.5 依赖图:把"递归"两个字看明白
main.js
├── import Vue → node_modules/vue/dist/vue.runtime.esm.js
├── import App → src/App.vue
│ ├── <script> import HelloWorld → components/HelloWorld.vue
│ │ ├── import xxx...
│ │ └── ...
│ └── <style> import './a.scss'
├── import router → src/router/index.js
│ └── import Home → views/Home.vue
│ └── import ...
└── import store → src/store/index.js
关键在递归:webpack 处理 App.vue 时发现它又 import 了 HelloWorld.vue,就把 HelloWorld.vue 也加进队列,继续拆、继续追,直到没有任何新的 import 为止。
这张图就是 webpack 的全部心智模型:
从入口出发 → 顺着 import 把文件全找齐(依赖图)→ 每个文件按规则交给对应 loader 加工 → 在流程节点上让 plugin 干活 → 最后合并成几个 bundle 输出。
而 Vue CLI 做的事,就是把这张图需要的所有规则、loader、plugin 都提前配好了,所以你写 Vue 时几乎感觉不到 webpack 存在。一旦你要改配置(比如加个 alias、改个代理),才需要掀开这层盖子去 vue.config.js 里动手。
第 7 章 启动流程:npm run serve 发生了什么
你敲下 npm run serve 到浏览器出现页面,中间经历了一整套流程。理解它,你就能自己排查各种启动报错。
7.1 命令的传导链
npm run serve
└─ 查 package.json 的 scripts.serve
└─ "vue-cli-service serve"
└─ 调用 @vue/cli-service 里的服务
└─ 读取 vue.config.js(如果有)
└─ 启动 webpack-dev-server
└─ webpack 编译 → 产物放【内存】→ 起本地服务器 → 打开浏览器
关键点:开发模式下编译产物不写到磁盘,而是放在内存里,由 webpack-dev-server 提供服务。这就是为什么 npm run serve 后项目目录里找不到 dist 文件夹——它在内存里,速度更快。
7.2 热更新 HMR(Hot Module Replacement)
改一行代码,浏览器自动刷新且不丢失当前页面状态(比如你在表单里填了一半的内容还在),这就是 HMR。原理简化版:
- dev-server 和浏览器之间建了一条 WebSocket 长连接
- webpack 监听文件变化,某个模块改了就单独重新编译它
- 通过 WebSocket 通知浏览器:"这个模块变了,替换掉"
- 浏览器热替换该模块,无需整页刷新
7.3 三种启动报错的高频原因
| 现象 | 常见原因 | 解法 |
|---|---|---|
| 端口 8080 被占用 | 上次没关干净 / 别的项目在跑 | CLI 会问是否换端口,选 Yes;或改 devServer.port |
缺依赖报错 Cannot find module 'xxx' | node_modules 不全 | 先 npm install;仍不行就 rm -rf node_modules && npm ci(只删 node_modules,别删 package-lock.json,见 1.4 / 附录 A) |
| sass/node-sass 相关报错 | Node 版本太新,老 node-sass 编译不过 | 用 dart-sass(sass 包),或降级 Node 到 16 |
第 8 章 Vue Router:页面是怎么切换的
SPA 的精髓就是前端路由。你选了 Router,这一章讲透它。
8.1 为什么需要前端路由
传统网站每点一个链接都向服务器请求一个新 HTML 页面,体验割裂。SPA 只有一个 index.html,切换"页面"其实是 JS 根据 URL 变化,动态换掉 <router-view> 里显示的组件——不刷新、秒切。
8.2 路由配置文件 router/index.js
import Vue from 'vue'
import VueRouter from 'vue-router'
import Home from '../views/Home.vue'
Vue.use(VueRouter) // 安装路由插件
const routes = [
{
path: '/',
name: 'Home',
component: Home // 直接引入(打包时打进主包)
},
{
path: '/about',
name: 'About',
// 路由懒加载:访问到这个路由才加载对应代码(第14章讲优化)
component: () => import('../views/About.vue')
},
{
path: '/user/:id', // 动态路由参数
name: 'User',
component: () => import('../views/User.vue'),
props: true // 把 :id 作为 props 传给组件
},
{
path: '*', // 404 兜底,放最后
name: 'NotFound',
component: () => import('../views/404.vue')
}
]
const router = new VueRouter({
mode: 'history', // history 模式(URL 不带 #,好看);默认 hash 模式
base: process.env.BASE_URL,
routes
})
export default router
8.3 hash 模式 vs history 模式(必懂)
| 模式 | URL 样子 | 原理 | 缺点 |
|---|---|---|---|
| hash | http://a.com/#/about | 用 URL 的 # 后面部分,hashchange 事件监听 | 带个 # 不好看;# 后的路径不会发给服务器 |
| history | http://a.com/about | 用 HTML5 history.pushState API | 刷新会 404!需要服务器配合 |
hash 模式的真正短板不是"SEO 差":老教程常说"hash 不利于 SEO",这个说法过于绝对——主流搜索引擎已能执行 JS 渲染,单纯因为带
#就完全抓不到内容的时代过去了。但硬限制仍在:#后面的内容浏览器根本不会发给服务器,于是服务端日志、统计、社交分享抓取(多数爬虫不执行 JS、也拿不到 hash)都拿不到完整路径,也没法做服务端渲染(SSR)。所以生产项目通常选 history + 服务器兜底。history 模式刷新 404 的坑:用户直接在地址栏敲
http://a.com/about,浏览器会真的向服务器请求/about这个文件,服务器上没这个文件就 404。解法是服务器配置兜底:所有路径都返回 index.html,让前端路由接管。Nginx 配法见第 15 章。
8.4 在组件里用路由
<template>
<div>
<!-- 声明式导航:渲染成 <a> 标签 -->
<router-link to="/about">关于</router-link>
<!-- 编程式导航:JS 里跳转 -->
<button @click="goUser">查看用户</button>
<!-- 路由匹配的组件渲染在这 -->
<router-view />
</div>
</template>
<script>
export default {
methods: {
goUser() {
// ⚠️ 下面是三种【任选其一】的写法,注释掉的留作参考。
// 千万别连着执行:会连续跳转三次,最后还被 replace 带回首页。
this.$router.push('/user/123') // ① 字符串路径
// this.$router.push({ name: 'User', params: { id: 123 } }) // ② 命名路由 + params
// this.$router.push({ path: '/about', query: { tab: 'info' } }) // ③ 带 query
},
goBack() {
this.$router.back() // 后退
},
goHome() {
this.$router.replace('/') // 替换当前历史(后退不回到上一页)
}
},
created() {
// 读取路由信息
console.log(this.$route.params.id) // 动态参数
console.log(this.$route.query.tab) // query 参数
console.log(this.$route.path) // 当前路径
}
}
</script>
$router和$route的区别(新手必混):
$router:路由器实例,用来"做动作"(跳转 push/replace/back)$route:当前路由信息对象,用来"读数据"(params/query/path)
8.5 路由守卫:拦截与控制
守卫是路由跳转过程中的"关卡",常用于登录鉴权。
// 全局前置守卫:每次跳转前都会经过
router.beforeEach((to, from, next) => {
const token = localStorage.getItem('token')
if (to.meta.requiresAuth && !token) {
next('/login') // 需要登录但没登录,踢去登录页
} else {
next() // 放行
}
})
配合路由元信息:
{
path: '/dashboard',
component: () => import('../views/Dashboard.vue'),
meta: { requiresAuth: true, title: '控制台' }
}
守卫类型(了解即可,用得最多的是全局前置):
- 全局:
beforeEach/afterEach - 路由独享:
beforeEnter(写在某条路由配置里) - 组件内:
beforeRouteEnter/beforeRouteUpdate/beforeRouteLeave
第 9 章 Vuex:全局状态怎么管
9.1 为什么需要 Vuex
父子组件传值用 props / $emit 够用。但当多个不相干的组件要共享同一份数据(如用户登录信息、购物车),层层传值会变成噩梦。Vuex 提供一个全局唯一的数据仓库,任何组件都能读、能改,且改动可追踪。
9.2 核心五概念(先记这张图)
组件 dispatch
│
▼
Actions ──(异步:调接口)──► 可以再 commit
│
▼ commit
Mutations ──(同步:改数据)──► 唯一能改 state 的地方
│
▼
State ──(数据)──► 组件通过 mapState/getter 读取
│
Getters ──(派生计算)──► 类似 computed
铁律:组件不能直接改 state,必须 commit 一个 mutation;异步操作(如请求接口)放 action 里,action 再去 commit mutation。这样每一次数据变化都有迹可循,方便调试。
9.3 store/index.js 实例
import Vue from 'vue'
import Vuex from 'vuex'
import axios from 'axios' // ← 别漏:下面 actions 里真用到了(第 10 章会封装成 request)
Vue.use(Vuex)
export default new Vuex.Store({
// 1. 状态数据
state: {
token: localStorage.getItem('token') || '',
userInfo: {},
count: 0
},
// 2. 派生状态(类似 computed,带缓存)
getters: {
isLogin: state => !!state.token,
doubleCount: state => state.count * 2
},
// 3. 同步修改(唯一能改 state 的地方)
mutations: {
SET_TOKEN(state, token) {
state.token = token
localStorage.setItem('token', token)
},
SET_USERINFO(state, info) {
state.userInfo = info
},
INCREMENT(state, n = 1) {
state.count += n
}
},
// 4. 异步操作(调接口在这里,再 commit)
actions: {
// context 是和 store 实例相同方法的对象,可解构出 commit
// ⚠️ 示例里必须真的 import 一个能发请求的东西;第 10 章会换成封装好的 @/utils/request
async login({ commit }, credentials) {
const { data: res } = await axios.post('/user/login', credentials)
commit('SET_TOKEN', res.token)
commit('SET_USERINFO', res.user)
return res
},
logout({ commit }) {
commit('SET_TOKEN', '')
commit('SET_USERINFO', {})
}
},
// 5. 模块拆分(项目大了按业务分模块)
modules: {
// cart, user, order ...
}
})
9.4 组件里怎么用 Vuex
<script>
import { mapState, mapGetters, mapMutations, mapActions } from 'vuex'
export default {
computed: {
// 把 state 映射成计算属性
...mapState(['token', 'userInfo', 'count']),
// 把 getter 映射成计算属性
...mapGetters(['isLogin', 'doubleCount'])
},
methods: {
// 把 mutation 映射成方法(同步)
...mapMutations(['INCREMENT', 'SET_TOKEN']),
// 把 action 映射成方法(异步)
...mapActions(['login', 'logout']),
async handleLogin() {
await this.login({ username: 'admin', password: '123' })
// 登录后 token 已存进 Vuex 和 localStorage
}
}
}
</script>
不用辅助函数也能手动访问:this.$store.state.count、this.$store.commit('INCREMENT')、this.$store.dispatch('login', data)。
9.5 模块化(中大型项目必备)
项目大了,全堆在一个文件里会爆炸。按业务拆模块:
// store/modules/user.js
export default {
namespaced: true, // ★ 开启命名空间,避免各模块同名冲突
state: () => ({ token: '', info: {} }),
mutations: { SET_TOKEN(state, t) { state.token = t } },
actions: { async login({ commit }, data) { /* ... */ } },
getters: { isLogin: s => !!s.token }
}
// store/index.js
import Vue from 'vue'
import Vuex from 'vuex'
import user from './modules/user'
Vue.use(Vuex) // ⚠️ 别漏:独立文件里也要重新 install 一次
export default new Vuex.Store({
modules: { user }
})
开启 namespaced 后,辅助函数要带模块名:
...mapState('user', ['token']),
...mapActions('user', ['login']),
// 手动调用:this.$store.dispatch('user/login', data)
9.6 Vuex 数据刷新丢失问题(必踩的坑)
Vuex 存在内存里,一刷新页面就清空。所以像 token 这种要持久化的,得配合 localStorage / sessionStorage(上面例子里已在 mutation 里同步写 localStorage,state 初始值从 localStorage 读,就是这个原因)。也可以用 vuex-persistedstate 插件自动持久化。
第 10 章 Axios:前后端数据交互
前端项目 80% 的复杂度在和后端打交道。Axios 是事实标准的 HTTP 请求库。
10.1 安装
npm install axios
10.2 为什么必须封装(而不是到处 axios.get)
直接散落各处写 axios.get('/api/user') 的问题:接口地址改了要改几十处、每个请求都要重复写 token、错误处理复制粘贴、无法统一 loading。所以生产项目一定封装。
10.3 一份生产级封装(utils/request.js)
import axios from 'axios'
import { Message } from 'element-ui' // 配合 UI 库弹提示
import store from '@/store'
import router from '@/router'
// 1. 创建实例,配基础地址
const request = axios.create({
baseURL: process.env.VUE_APP_API_BASE, // 从环境变量读,自动区分开发/生产
timeout: 10000 // 10 秒超时
})
// 2. 请求拦截器:请求发出前统一处理
request.interceptors.request.use(
config => {
// 带上 token
const token = store.state.token
if (token) {
config.headers.Authorization = `Bearer ${token}`
}
return config
},
error => Promise.reject(error)
)
// 3. 响应拦截器:拿到响应后统一处理
request.interceptors.response.use(
response => {
const { code, data, msg } = response.data
if (code === 200 || code === 0) { // 按后端约定判断成功
return data // 直接把 data 吐给业务层,少写一层
}
// 业务错误
Message.error(msg || '请求失败')
return Promise.reject(new Error(msg))
},
error => {
// HTTP 状态码错误
if (error.response) {
const { status } = error.response
switch (status) {
case 401:
Message.error('登录已过期,请重新登录')
store.dispatch('logout')
router.push('/login')
break
case 403:
Message.error('没有权限访问')
break
case 404:
Message.error('请求资源不存在')
break
case 500:
Message.error('服务器内部错误')
break
default:
Message.error(error.message)
}
} else {
Message.error('网络异常,请检查网络连接')
}
return Promise.reject(error)
}
)
export default request
10.4 按业务组织 API(api/user.js)
import request from '@/utils/request'
export function login(data) {
return request({ url: '/user/login', method: 'post', data })
}
export function getUserInfo() {
return request({ url: '/user/info', method: 'get' })
}
export function updateUser(id, data) {
return request({ url: `/user/${id}`, method: 'put', data })
}
组件里用:
import { login, getUserInfo } from '@/api/user'
async function handleLogin() {
try {
const data = await login({ username, password }) // 拦截器已把 data 解出来了
console.log('登录成功', data)
} catch (e) {
// 错误已在拦截器弹过提示,这里只处理业务后续
}
}
@/是什么? 是src/的别名(alias),Vue CLI 默认配好了。@/utils/request就是src/utils/request.js,避免写一长串../../../。
10.5 跨域与代理:开发环境怎么连后端
跨域是什么:浏览器同源策略限制——前端跑在 localhost:8080,后端在 localhost:3000,端口不同就算跨域,直接请求会被浏览器拦截。
开发环境解法:devServer 代理(回到第 5 章的 vue.config.js):
devServer: {
proxy: {
'/api': {
target: 'http://localhost:3000', // 后端真实地址
changeOrigin: true, // 把请求头 Host 改成 target 的域名(后端按域名校验时用)
pathRewrite: { '^/api': '' } // 把 /api 前缀去掉再转发
}
}
}
原理:请求发到自己的 dev-server(同源,不跨域),dev-server 再在服务器端转发给后端(服务器之间没跨域限制)。这样浏览器以为请求的是同源地址。
注意:代理只在开发模式生效!打包后没有 dev-server,生产环境的跨域要靠后端配 CORS 或 Nginx 反向代理(第 15 章)。
第 11 章 UI 组件库:以 Element UI 为例
Vue2 生态最主流的 UI 库就是 Element UI(饿了么出品)。它提供现成的表格、表单、弹窗、导航等几十个组件,让你不用从零写样式。
11.1 安装
npm install element-ui
11.2 完整引入(简单,适合快速起步)
在 main.js:
import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css' // ★ 别忘了引样式!
Vue.use(ElementUI)
之后任何组件里都能直接用:
<template>
<!-- ⚠️ Vue 2 的 template 必须有且只有一个根元素,所以要包一层 div -->
<div class="demo">
<el-button type="primary" @click="open">打开弹窗</el-button>
<el-table :data="list" border>
<el-table-column prop="name" label="姓名"></el-table-column>
<el-table-column prop="age" label="年龄"></el-table-column>
</el-table>
</div>
</template>
<script>
export default {
data() {
return { list: [{ name: '张三', age: 20 }] }
},
methods: {
open() {
this.$message.success('这是一条提示') // Message 组件
this.$confirm('确定删除吗?', '提示') // 确认弹窗
.then(() => this.$message('已删除'))
.catch(() => this.$message('已取消'))
}
}
}
</script>
⚠️ 为什么多了一个
<div class="demo">:Vue 2 的组件模板只允许一个根元素,把<el-button>和<el-table>并列放在<template>下,编译期就会报Component template should contain exactly one root element。多根节点(Fragment)是 Vue 3 才支持的。这是 Vue2 学习者最容易照抄翻车的一处。组件名都是
el-前缀(el-button、el-table),JS 调用的方法挂在this.$message、this.$confirm上(完整引入时由Vue.use(ElementUI)挂载)。
11.3 按需引入(优化,生产推荐)
完整引入会把整个库打进包里(体积大)。按需引入只打包你用到的组件。
⚠️ 先把上一版改反的地方填回去:Vue 2 + Element UI 官方指定的按需引入插件就是
babel-plugin-component(插件名写'component',配置键是libraryName/styleLibraryName)。babel-plugin-import是 Ant Design 系列用的通用按需引入插件,它的配置里没有styleLibraryName, 照搬到 Element UI 上最典型的结果就是"组件能用、样式全丢"。两个生态的插件别混用 (依据:Element UI 官方"快速上手 → 按需引入" 与babel-plugin-component仓库文档)。
npm install babel-plugin-component -D
babel.config.js(Vue CLI 5 项目用 babel.config.js,不是 .babelrc;preset 用 CLI 自带的,别照 Element 旧文档写 Babel 6 的 es2015):
module.exports = {
presets: ['@vue/cli-plugin-babel/preset'],
plugins: [
[
'component', // ← 插件名是 component,不是 import
{
libraryName: 'element-ui',
styleLibraryName: 'theme-chalk' // 自动带上对应组件的样式
}
]
]
}
两个高频翻车点
- Element 官网老示例里的
"presets": [["es2015", {"modules": false}]]是 Babel 6 的写法,直接贴进 CLI 5 会报Cannot find module 'babel-preset-es2015'。换成上面这行 CLI preset。- 改完
babel.config.js必须重启 dev server,babel 配置不参与热更新(附录 B 也有这条)。
新建 src/plugins/element.js 集中注册用到的组件:
import Vue from 'vue'
import { Button, Table, TableColumn, Message, MessageBox } from 'element-ui'
Vue.component(Button.name, Button) // 或 Vue.use(Button)
Vue.component(Table.name, Table)
Vue.component(TableColumn.name, TableColumn)
// Message / MessageBox 是方法型的,挂到原型上方便用
Vue.prototype.$message = Message
Vue.prototype.$confirm = MessageBox.confirm
main.js 里加一行 import '@/plugins/element',放在 new Vue() 之前。这样打包体积能小很多(第 14 章会量化)。
⚠️ 换成按需引入时,记得把 11.2 里的
import ElementUI from 'element-ui'、Vue.use(ElementUI)和全量index.css删掉,否则全量代码照样进包,按需引入等于白做。
如果
Message等组件的样式没跟着出来,可单独补一句import 'element-ui/lib/theme-chalk/message.css'。
现实建议:Vue CLI 5(webpack 5)下
babel-plugin-component仍可用,但 Element UI 2.x 已停止维护,按需引入遇到样式路径问题时,最稳的两条路是:
- 完整引入 + 第 14.3 节的 CDN 外链:让
element-ui走 CDN,不进 vendors,也不用折腾按需引入;- 新项目直接上 Vue 3 + Element Plus,按需引入是官方一等公民支持。
11.4 修改 Element 默认样式(scoped 穿透)
原理见第 6.3 节:Element 组件的根元素带着你的 data-v-x,内部元素不带。所以要分两种情况:
<style scoped>
/* ✅ 情况一:改【根元素】——不需要穿透,直接写就行 */
.el-button { border-radius: 20px; }
/* ✅ 情况二:改【内部元素】——才需要深度选择器穿透 */
::v-deep .el-input__inner { border-color: red; }
::v-deep .el-button span { font-weight: bold; }
/* 推荐写法:带上自己的外层类名,把作用范围圈在本组件内 */
.my-form ::v-deep .el-input__inner { border-color: red; }
</style>
注意别举反例:
::v-deep .el-button { ... }这种写法虽然能跑,但.el-button是组件根元素,本来就不用穿透——它体现不出穿透的价值,反而会让人误以为"改 Element 一律要加 ::v-deep"。Vue 3 项目里把
::v-deep换成:deep(.el-input__inner),且务必先试组件自带的 props / 配置项,穿透留作兜底。注意--el-input-border-color这类 CSS 变量属于 Vue 3 + Element Plus,Vue 2 + Element UI 没有,别照搬(见 6.3.7)。
第 12 章 代码规范:ESLint + Prettier
团队协作中,代码风格统一和质量检查靠这两个工具。创建项目时你选了 Linter,它已经配好了。
12.1 两者分工
| 工具 | 管什么 | 类比 |
|---|---|---|
| ESLint | 代码质量(有没有未使用变量、有没有语法隐患)+ 部分风格 | 语法老师:揪出错误和坏味道 |
| Prettier | 代码格式(缩进、引号、分号、换行) | 排版老师:只管好看,不改逻辑 |
12.2 .eslintrc.js 解读
module.exports = {
root: true,
env: { node: true, browser: true },
extends: [
'plugin:vue/essential', // Vue 官方规则
'@vue/standard' // Standard 风格(你创建时选的)
],
rules: {
'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
// 自定义:允许组件名多单词等
'vue/multi-word-component-names': 'off'
}
}
规则级别三档:'off'/0 关闭、'warn'/1 警告(不阻断)、'error'/2 报错(会阻断编译)。
12.3 配合 Prettier(推荐搭配)
npm install -D prettier eslint-plugin-prettier eslint-config-prettier
.prettierrc:
{
"semi": false,
"singleQuote": true,
"printWidth": 100,
"trailingComma": "none"
}
lintOnSave的坑:CLI 5 默认值'default'(等价于true),一个 ESLint error 就会让开发服务器编译失败、浏览器弹出错误遮罩。新手常被这个劝退。可以临时设false或'warning'只在控制台提示不阻断。
12.4 编辑器配合(VS Code)
先记死一条:Vetur 和 Volar 是互斥的,装了两个会打架(它们都抢 TS/模板语言服务,结果是满屏飘红、跳转失效)。所以必须按 Vue 版本二选一,并禁用另一个:
| 你的项目 | 装哪个 | 另一个怎么处理 |
|---|---|---|
| Vue 2 | Vetur(语法高亮 / snippets / 格式化) | 禁用 Volar / Vue - Official |
| Vue 3 或 Vue 2.7 | Vue - Official(原 Volar) | 禁用或卸载 Vetur |
- 如果你在 Vue 2.7 项目上想用新插件:Vue - Official 主要面向 Vue 3,对 Vue 2 的支持需要按官方文档额外配置(涉及
vueCompilerOptions与配套依赖),并不存在"点一下开关就兼容 Vue 2"的通用设置。新手别在这里折腾,Vetur 更省心;确有新插件需求时以该插件官方文档的 Vue 2 配置说明为准。 - 再装 ESLint + Prettier 两个插件,打开"保存时自动格式化"(
editor.formatOnSave),并把 ESLint 设为保存时自动修复(source.fixAll.eslint),体验拉满。 - 装完如果还报错,先去"已禁用"列表里确认 Vetur/Volar 没有同时启用,这是 90% 的"插件莫名报错"的根因。
第 13 章 打包:npm run build 与产物分析
开发完了,要把项目交付给用户,就得打包。
13.1 执行打包
npm run build
对应 "build": "vue-cli-service build"。它会:
- 以
production模式加载.env.production环境变量 - webpack 用生产配置编译(压缩、混淆、tree-shaking、代码分割)
- 产物输出到
dist/目录
成功输出(以下按 assetsDir 默认值 '' 展示,所以是 dist/js/...;若像 5.1 那样设了 assetsDir: 'static',路径会变成 dist/static/js/...):
File Size Gzipped
dist/js/chunk-vendors.3f2a.js 320.50 KiB 105.20 KiB
dist/js/app.8c1d.js 45.30 KiB 15.10 KiB
dist/css/app.4e9f.css 28.70 KiB 6.80 KiB
dist/index.html 0.60 KiB 0.35 KiB
⚠️ 别把 5.1 里"设了
assetsDir: 'static'"和这份默认输出混着看:同一份配置不可能同时输出两种路径。
13.2 dist 目录里都是什么
dist/ # 下图沿用 5.1 的配置 assetsDir: 'static'
├── index.html # 入口 HTML(自动注入了打包后的 js/css 链接)
├── favicon.ico
├── static/ # ⚠️ 默认 assetsDir 是 '',此时【没有这一层】,js/css 直接放 dist/ 下
│ ├── css/app.[hash].css # 所有样式合并压缩
│ ├── js/
│ │ ├── app.[hash].js # 你的业务代码
│ │ ├── chunk-vendors.[hash].js # 第三方库(vue、element、axios...)
│ │ └── about.[hash].js # 懒加载 chunk(名字取决于 webpackChunkName,未指定时常是数字 id)
│ └── img/logo.[hash].png
想让懒加载分包叫
about.xxx.js,要在import()里加魔法注释:() => import(/* webpackChunkName: "about" */ '../views/About.vue'),否则文件名通常是数字 id 或chunk-xxx。
几个关键现象要能解释:
- 文件名带 hash(如
app.8c1d.js):内容变了 hash 才变。配合 HTTP 强缓存,用户下次访问命中缓存秒开;你发新版 hash 变了,浏览器自动拉新文件。这就是"缓存破坏(cache busting)"。 - app 和 chunk-vendors 分开:业务代码改得勤、第三方库很少改,拆开后用户更新时只需重新下载小的 app.js,大的 vendors 走缓存。
- 路由懒加载产生了单独的小 js:访问 About 页才下载
about.js。
13.3 产物体积分析(优化前的体检)
想知道到底是什么占了体积,用 webpack-bundle-analyzer:
npm install -D webpack-bundle-analyzer
vue.config.js:
const { defineConfig } = require('@vue/cli-service') // ← 别漏,否则 defineConfig is not defined
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
module.exports = defineConfig({
chainWebpack: (config) => {
if (process.env.NODE_ENV === 'production') {
config.plugin('analyzer').use(BundleAnalyzerPlugin, [{
analyzerMode: 'static', // 生成报告 HTML
openAnalyzer: false
}])
}
}
})
打包后会在输出目录生成一份 report.html(上面设了 openAnalyzer: false,所以不会自动弹浏览器,自己打开这个 HTML 即可)。方块越大体积越大,一眼看出"是不是 Element UI 全量引入占了 500KB"。优化永远是"先测量,再动手"。
13.4 本地预览打包结果
dist 是纯静态文件,不能直接双击 index.html 打开(路径、history 路由都会出问题)。用本地服务器预览:
# 方式一:用 serve 工具
npm install -g serve
serve -s dist
# 方式二:用任何静态服务器,如 http-server、Nginx
第 14 章 打包优化实战
产物分析出问题后,常见的优化手段。这一章是"中级 → 高级"的分水岭。
14.1 路由懒加载(收益最大、最简单)
第 8 章的 () => import('../views/About.vue') 就是懒加载。首页只加载首页代码,其他路由按需加载。首屏体积能立降一大块。把路由配置里的静态 import 全改成动态 import 即可。
14.2 UI 库按需引入
第 11 章讲过。Element UI 完整引入约 500KB+,按需引入只带用到的组件,能省几百 KB。
14.3 CDN 外链大库
把 vue、element-ui 这些稳定大库走 CDN(浏览器还能跨站缓存),不打包进 vendors:
vue.config.js:
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
configureWebpack: {
externals: {
vue: 'Vue',
'element-ui': 'ELEMENT',
axios: 'axios'
}
}
})
public/index.html 里手动引 CDN:
<script src="https://unpkg.com/vue@2.6.14/dist/vue.min.js"></script>
<script src="https://unpkg.com/element-ui@2.15.13/lib/index.js"></script>
<script src="https://unpkg.com/axios@0.27.2/dist/axios.min.js"></script>
externals的作用是告诉 webpack:"遇到import Vue from 'vue'别打包,运行时从全局变量Vue拿"。
14.4 关闭生产 source map
productionSourceMap: false
source map 是源码映射文件(方便线上调试),但体积大且暴露源码。生产关掉,打包更快、包更小、更安全。
14.5 图片压缩与转 base64
- 小图转 base64 内联进代码,省掉一次 HTTP 请求。但这不是 webpack 的自动行为,而是由专门的资源处理规则干的:
- webpack 5:内置的
asset模块类型(parser.dataUrlCondition.maxSize,见第 16.3 节) - webpack 4 及更早:
url-loader - Vue CLI 5 的默认阈值是 8 KiB(8192 字节),不是 4KB;想改就在
vue.config.js里覆盖:chainWebpack: config => { config.module.rule('images') .set('parser', { dataUrlCondition: { maxSize: 16 * 1024 } }) // 调大到 16 KiB }依据:Vue CLI 官方文档《HTML 和静态资源》 一节明确"将小于 8KiB 的资源内联",其示例是把默认阈值调小到 4KiB(
maxSize: 4 * 1024)。调大调小按业务需要,但别把默认值记反。(16.3 手写配置里写的4 * 1024是自己定的值,与 CLI 默认值无关。)
注意:阈值调太大反而有害——base64 会让 JS/CSS 体积膨胀约 33%,而且失去独立缓存(改一个字节,整份 bundle 缓存全失效)。
- webpack 5:内置的
- 大图用
image-webpack-loader压缩,或上传到 OSS/CDN 用外链
14.6 gzip 压缩(部署侧)
打包时可生成 .gz 文件(compression-webpack-plugin),或干脆让 Nginx 开 gzip 动态压缩。文本资源 gzip 后通常能压到原来的 1/3。
14.7 优化清单速查
| 手段 | 难度 | 收益 | 优先级 |
|---|---|---|---|
| 路由懒加载 | 低 | 高 | ⭐⭐⭐ 必做 |
| UI 库按需引入 | 低 | 高 | ⭐⭐⭐ 必做 |
| 关 source map | 低 | 中 | ⭐⭐⭐ 必做 |
| CDN 外链 | 中 | 中 | ⭐⭐ |
| Nginx gzip | 低 | 高 | ⭐⭐⭐ 必做 |
| 图片优化 | 中 | 中 | ⭐⭐ |
| 依赖分析后针对性处理 | 高 | 视情况 | ⭐ |
第 15 章 部署上线
打包出的 dist 是一个纯静态站点,需要一个 Web 服务器托管。生产最常用 Nginx。
15.1 最简部署
把 dist 里所有文件传到服务器某个目录(如 /usr/share/nginx/html),配一段 Nginx:
server {
listen 80;
server_name your-domain.com;
root /usr/share/nginx/html; # dist 内容放这
index index.html;
# ★ history 模式关键:所有路径都回退到 index.html,交给前端路由
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源长缓存(文件名带 hash,可放心缓存一年)
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# 开启 gzip
gzip on;
gzip_types text/plain text/css application/json application/javascript;
# 反向代理解决生产跨域(对应开发环境 devServer.proxy)
location /api/ {
proxy_pass http://backend-server:3000/;
}
}
try_files $uri $uri/ /index.html就是第 8 章说的 history 模式刷新 404 的解法:找不到真实文件就返回 index.html,让 Vue Router 接管路由。
15.2 publicPath 与部署路径
如果你不是部署在域名根目录,而是子路径(如 https://a.com/admin/),要改 vue.config.js:
publicPath: '/admin/' // 默认 '/'
否则页面白屏、资源 404(这是超高频部署事故)。
15.3 现代部署:CI/CD
正规团队不会手动传文件,而是配 CI/CD(如 GitHub Actions、GitLab CI、Jenkins):代码推到仓库 → 自动 npm install && npm run build → 自动传 dist 到服务器。这属于进阶运维范畴,知道有这么回事即可。
第 16 章 从零手写 webpack 配置(进阶对比)
这一章是打开黑盒。 前面你一直用 Vue CLI,webpack 被藏起来了。现在我们用最朴素的方式,手写一个能跑的 Vue2 + webpack 项目,你会瞬间理解 CLI 到底帮你做了什么。
16.1 初始化一个裸项目
mkdir vue-handwrite && cd vue-handwrite
npm init -y
16.2 安装需要的包(体会 CLI 帮你省了多少事)
# ⚠️ 手写项目【必须锁版本】:不写版本号会装到 Vue 3 专用的 vue-loader@17,
# 和 Vue 2 的 vue-template-compiler 直接冲突,照着做必然报错。
npm install vue@2.6.14
# 核心(webpack 5 这一套)
npm install -D webpack@5 webpack-cli@5 webpack-dev-server@4
# 处理 .vue:Vue 2 对应 vue-loader 15
npm install -D vue-loader@15 vue-template-compiler@2.6.14
# 处理 JS
npm install -D babel-loader@9 @babel/core @babel/preset-env
# 处理样式
npm install -D css-loader style-loader sass sass-loader@12
# 生成 HTML / 抽离 CSS
npm install -D html-webpack-plugin@5 mini-css-extract-plugin@2
光看这一长串,你就该感谢 Vue CLI 了——它把这些全装好、配好、还保证了版本兼容。
⚠️ 两个必踩的坑
vue和vue-template-compiler的版本号必须完全一致(上面都锁2.6.14)。不一致时编译直接报Vue packages version mismatch: vue@2.6.14 - vue-template-compiler@2.7.16——compiler 要按 vue 运行时的内部结构生成 render 函数,版本错开就对不上。每次升级 vue,记得同步升 vue-template-compiler。vue-loader必须是 15.x。vue-loader@16/17是给 Vue 3 用的,且VueLoaderPlugin的引入路径也变了(16.3 用的是vue-loader/lib/plugin,属于 15.x 写法)。
16.3 手写 webpack.config.js
const path = require('path')
const VueLoaderPlugin = require('vue-loader/lib/plugin')
const HtmlWebpackPlugin = require('html-webpack-plugin')
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
const isProd = process.env.NODE_ENV === 'production'
module.exports = {
mode: isProd ? 'production' : 'development',
entry: './src/main.js', // 入口
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'js/[name].[hash:8].js',
clean: true // 打包前清空 dist
},
resolve: {
extensions: ['.js', '.vue', '.json'], // 可省略的后缀
alias: { '@': path.resolve(__dirname, 'src') } // @ 别名(CLI 自带的那个)
},
module: {
rules: [
{
test: /\.vue$/,
loader: 'vue-loader' // 处理 .vue
},
{
test: /\.js$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader', // 降级 JS
options: { presets: ['@babel/preset-env'] }
}
},
{
test: /\.s?css$/,
use: [
isProd ? MiniCssExtractPlugin.loader : 'style-loader',
'css-loader', // 解析 @import / url()
'sass-loader' // scss → css
]
},
{
test: /\.(png|jpe?g|gif|svg)$/,
type: 'asset', // webpack5 内置资源处理(小图转 base64)
parser: { dataUrlCondition: { maxSize: 4 * 1024 } }
}
]
},
plugins: [
new VueLoaderPlugin(), // ★ vue-loader 必须配这个插件
new HtmlWebpackPlugin({
template: './public/index.html' // 用它生成注入了 js/css 的 index.html
}),
...(isProd ? [new MiniCssExtractPlugin({ filename: 'css/[name].[hash:8].css' })] : [])
],
devServer: {
port: 8080,
open: true,
hot: true,
proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true } }
}
}
还差三个文件才能真的跑起来:
src/main.js、src/App.vue、public/index.html(内容照第 4 章抄)。另外vue-loader@15必须配new VueLoaderPlugin(),漏了会报vue-loader was used without the corresponding plugin。 这里的maxSize: 4 * 1024是手写配置里自己定的阈值;Vue CLI 5 的默认阈值是 8 KiB(见 14.5),两者不冲突。
16.4 对照:CLI 帮你做了什么
现在把这份手写配置和 Vue CLI 对照,一切豁然开朗:
| 手写配置里的一段 | Vue CLI 里对应的"魔法" |
|---|---|
entry: './src/main.js' | CLI 默认入口就是 src/main.js |
HtmlWebpackPlugin + template | CLI 默认用 public/index.html |
vue-loader + VueLoaderPlugin | CLI 内置,装都不用装 |
babel-loader + preset-env | CLI 的 @vue/cli-plugin-babel |
css-loader/sass-loader/style-loader | CLI 内置,装 sass 包即可用 |
alias: { '@': src } | CLI 默认就配好了 @ |
devServer.proxy | 就是 vue.config.js 里的 devServer.proxy |
MiniCssExtractPlugin | CLI 生产模式自动做 |
图片 asset 处理 | CLI 内置,默认小于 8KiB 内联 base64(见 14.5) |
mode 切换 | npm run serve/build 自动切换 |
结论:vue.config.js 里的每一个选项,最终都会被 CLI 合并进一份和上面高度相似的 webpack 配置。你写 vue.config.js,本质上就是在"改这张表的某一行"。
16.5 什么时候真的需要手写
- 学习原理(就像现在) ✅
- 极端定制需求,CLI 的
chainWebpack都满足不了 - 维护一些没有用 CLI 的老项目
日常业务开发,用 Vue CLI(或更新的 Vite)+ vue.config.js 覆盖就是最优解。
第 17 章 一条完整的开发闭环(总结)
把前面所有环节串成你日常会走一遍的完整流程:
① 创建 vue create my-project (第3章)
│
② 配置 vue.config.js + .env.* (第5章)配代理、路径、环境变量
│
③ 开发 npm run serve (第7章)
│ ├─ 写 .vue 组件 (第4章)
│ ├─ 配路由 router (第8章)
│ ├─ 写 Vuex 管全局状态 (第9章)
│ ├─ 封装 axios 调接口 (第10章)
│ ├─ 用 Element UI 搭界面 (第11章)
│ └─ ESLint 保代码质量 (第12章)
│
④ 打包 npm run build (第13章)
│ └─ 优化:懒加载/按需/CDN/gzip (第14章)
│
⑤ 部署 dist → Nginx (第15章)
└─ try_files 解决 history 404
你现在应该能回答这些问题(检验掌握程度):
npm run serve和npm run build的本质区别?→ 开发态内存编译+热更新 vs 生产态磁盘输出+压缩vue.config.js是干嘛的?→ 覆盖 CLI 内置的 webpack 配置- 环境变量为什么要用
VUE_APP_开头?→ CLI 白名单,DefinePlugin 文本替换 $router和$route区别?→ 动作 vs 信息- Vuex 里异步操作放哪?→ actions,再 commit 同步的 mutation
- 开发环境跨域怎么解决?生产呢?→ devServer 代理 / Nginx 反向代理或 CORS
- history 模式刷新 404 为什么?怎么解?→ 服务器没该文件,Nginx try_files 兜底
- 打包体积大先干嘛?→ 先用 bundle-analyzer 测量,再懒加载/按需/去 source map
能答上这 8 个,你就已经从"会写 Vue 组件"跨到了"懂 Vue 工程化"。
附录 A 常用命令速查
# 安装与初始化
npm install -g @vue/cli # 全局装脚手架
vue create <项目名> # 创建项目
npm install # 装依赖(clone 项目后第一步)
npm install <包名> # 装运行时依赖
npm install <包名> -D # 装开发依赖
npm install <包名>@<版本> # 装指定版本
# 开发
npm run serve # 启动开发服务器
npm run lint # 代码检查并自动修复部分问题
# 构建
npm run build # 生产打包
serve -s dist # 本地预览打包产物
# 排查
npm outdated # 查看哪些依赖过时
npm ls <包名> # 查看某包版本和依赖树
rm -rf node_modules && npm ci # 依赖出问题:按 lock 精确重装(不要删 package-lock.json!)
# vue 相关
vue --version # CLI 版本
vue add <插件> # 给已有项目加官方插件(如 vue add router)
附录 B 常见坑与排查
| 症状 | 最可能的原因 | 解决 |
|---|---|---|
vue 不是内部或外部命令 | CLI 没全局装 / PATH 没配 | 重装 CLI,配 npm 全局路径到环境变量 |
node-sass 编译报错 | Node 版本与 node-sass 不匹配 | 改用 sass(dart-sass),或 Node 降到 16 |
Error: error:0308010C:digital envelope routines | Node 17+ 的 OpenSSL 3 移除了 md4,与老 webpack 4 冲突(webpack 5 / CLI 5 不受影响) | 临时:Linux/mac export NODE_OPTIONS=--openssl-legacy-provider;Windows set NODE_OPTIONS=--openssl-legacy-provider;或升级 webpack 5 / 降 Node |
| 保存代码直接白屏/编译失败 | lintOnSave: true 时 ESLint error 阻断 | 改 'warning' 或修掉 ESLint 错误 |
| 打包后部署白屏 | publicPath 不对 / history 路由没配兜底 | 改成正确的子路径;Nginx 加 try_files |
| 开发环境接口 404/跨域 | 代理没配对 / baseURL 写错 | 检查 devServer.proxy 和 VUE_APP_API_BASE |
| 改了代码页面没变 | 缓存 / 改的是 public 里的文件 | 硬刷新;理解 public 不参与热更新 |
| scoped 样式改不动第三方组件 | data-v-x 只加在本组件模板编译出的元素 + 子组件根元素上,子组件内部元素没有(详见 6.3) | 改根元素不用穿透;改内部元素用 ::v-deep(Vue 2)/ :deep()(Vue 3),优先试 props / 非 scoped 全局类名 |
改了 babel.config.js 没生效 | babel 配置不参与热更新 | 必须重启 dev server |
Vue packages version mismatch | vue 与 vue-template-compiler 版本不一致 | 两个包锁到同一版本号(见 16.2) |
Element 按需引入后样式全丢 / Cannot find module 'babel-preset-es2015' | 插件用错(抄了 babel-plugin-import),或把 Element 官网的 Babel 6 es2015 preset 贴进了 CLI 5 | Vue 2 + Element UI 用 babel-plugin-component(插件名 'component' + styleLibraryName),preset 换成 @vue/cli-plugin-babel/preset,改完重启 dev server(见 11.3) |
| 满屏飘红、跳转失效(VS Code) | Vetur 和 Volar 同时启用,抢语言服务 | 禁用其中一个,Vue2 用 Vetur、Vue3 用 Vue - Official |
| 刷新页面 Vuex 数据没了 | Vuex 在内存,刷新即清 | localStorage 持久化或用 vuex-persistedstate |
| 图片不显示 | public 和 assets 引用方式用错 | public 用绝对路径 /x.png,assets 用相对/import |
结语
这份文档从"浏览器看不懂 .vue 文件"讲起,一路走到了 Nginx 部署和手写 webpack 配置。核心脉络其实就一句话:
你写的 Vue 源码,被 webpack(藏在 Vue CLI 里)顺着 import 织成依赖图、经各种 loader/plugin 加工,在开发态放内存里热更新供你调试,在生产态压缩分块输出成 dist 静态文件,最后丢给 Nginx 托管给用户。Router 管页面切换,Vuex 管全局数据,Axios 管前后端通信,Element UI 管界面,ESLint 管质量。
把这条线记牢,再遇到任何 Vue2 项目,你都能快速定位"这个文件/这个配置在这条线的哪一环",这就是工程化思维。接下来最好的学习方式就是:打开你创建的项目,对照本文档,把每一章对应的文件亲自点开看一遍、改一改、重启试试。动手一次,胜过读十遍。
祝学习顺利!🚀