Vue2 前端项目开发完全指南

4 阅读42分钟

面向:会一点 Vue2 语法、但不了解整体架构的同学 目标:从"会写组件"到"能独立搭建、配置、启动、打包一个完整生产级 Vue2 项目" 主线:以 Vue CLI(webpack) 为主,贯穿对比纯手写 webpack 项目,让你既会用脚手架,也看得懂底层


目录


第 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 文件:

  1. <template> → 编译成渲染函数(JS)
  2. <script> → 处理成浏览器能跑的 JS
  3. <style> → 抽出来变成真正的 CSS
  4. 把你项目里成百上千个这样的文件,合并、压缩、优化成几个 .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 Xexport 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 语法,是 webpack resolve.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 内置了三种模式:

模式触发命令加载的文件
developmentnpm run serve.env + .env.development
productionnpm 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

三块分别加工:

  1. template 块 → vue-template-compiler 把 HTML 模板编译成一个 JS 函数(render 函数)。你写的 <div>{{ msg }}</div> 最终变成类似 _c('div', [_v(_s(msg))]) 的函数调用。浏览器不认模板,只认这个函数。
  2. script 块 → 就是普通 JS,走 babel-loader 降级。
  3. 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

两个必须知道的点:

  1. 作用域没有消失,只是边界前移了。写法 A 会命中本组件内任意位置的 .el-input__inner(包括你自己写的),容易误伤;所以推荐写法 B,用外层类名把范围圈住。
  2. ::v-deep 前面要有空格。::v-deep .el-input__inner 是"后代选择器";写成 .my-input::v-deep .el-input__inner(没空格)含义完全不同,会贴到 .my-input 上。

各版本写法对照(照着用,别混):

写法适用注意
>>>仅纯 CSSSCSS/Less 会把它当除号/组合符,直接语法报错
/deep/Vue 2 可用已废弃,新版 Dart Sass 会输出 deprecation 警告
::v-deepVue 2 通用Vue 2 里最稳的选择
:deep()Vue 3 官方,Vue 2.7 起也支持Vue 3 里写 ::v-deep .foo 这种组合符形式已废弃并会警告,必须写成 :deep(.foo)

6.3.6 三个常被追问的 scoped 副作用

  1. v-html 插入的内容不带 data-v-x,所以 scoped 样式对它完全无效。解法:给 v-html 外层包一个普通 class,用非 scoped 的 <style> 块写。
  2. body / html / #app 这类根级选择器会失效。因为它们被改写成 body[data-v-x],而 <body> 上根本没有这个属性。这类全局样式请写在不带 scoped 的 <style> 里。
  3. 穿透会让样式"漏"到子组件,这是既定行为不是 bug;反过来,父组件想改子组件根元素的样式是不需要穿透的(根元素本来就有父的 data-v-x)。

6.3.7 比穿透更优先的三种做法

穿透是兜底手段,优先级应该排在最后:

  1. 组件自带的 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 不支持,写了不会有任何效果。

  2. 非 scoped 的 <style> 块 + 全局唯一类名(一定要包一层,否则污染全局):
    <style>
    .my-page-unique .el-input__inner { border-color: red; }
    </style>
    
  3. :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 管不管
语法?. ?? 箭头函数 解构 class async/await✅ 管,会转写
APIPromise、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 已经内置了这套机制,你只要确保两件事:

  1. .browserslistrc 里真的写了要支持的老浏览器(比如 ie 11);配了 IE11,CLI 才会自动注入对应的垫片。
  2. 别把 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。原理简化版:

  1. dev-server 和浏览器之间建了一条 WebSocket 长连接
  2. webpack 监听文件变化,某个模块改了就单独重新编译它
  3. 通过 WebSocket 通知浏览器:"这个模块变了,替换掉"
  4. 浏览器热替换该模块,无需整页刷新

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 样子原理缺点
hashhttp://a.com/#/about用 URL 的 # 后面部分,hashchange 事件监听带个 # 不好看;# 后的路径不会发给服务器
historyhttp://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'          // 自动带上对应组件的样式
      }
    ]
  ]
}

两个高频翻车点

  1. Element 官网老示例里的 "presets": [["es2015", {"modules": false}]] 是 Babel 6 的写法,直接贴进 CLI 5 会报 Cannot find module 'babel-preset-es2015'。换成上面这行 CLI preset。
  2. 改完 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 已停止维护,按需引入遇到样式路径问题时,最稳的两条路是:

  1. 完整引入 + 第 14.3 节的 CDN 外链:让 element-ui 走 CDN,不进 vendors,也不用折腾按需引入;
  2. 新项目直接上 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 2Vetur(语法高亮 / snippets / 格式化)禁用 Volar / Vue - Official
Vue 3 或 Vue 2.7Vue - 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"。它会:

  1. 以 production 模式加载 .env.production 环境变量
  2. webpack 用生产配置编译(压缩、混淆、tree-shaking、代码分割)
  3. 产物输出到 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 缓存全失效)。

  • 大图用 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 了——它把这些全装好、配好、还保证了版本兼容。

⚠️ 两个必踩的坑

  1. 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。
  2. 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 + templateCLI 默认用 public/index.html
vue-loader + VueLoaderPluginCLI 内置,装都不用装
babel-loader + preset-envCLI 的 @vue/cli-plugin-babel
css-loader/sass-loader/style-loaderCLI 内置,装 sass 包即可用
alias: { '@': src }CLI 默认就配好了 @
devServer.proxy就是 vue.config.js 里的 devServer.proxy
MiniCssExtractPluginCLI 生产模式自动做
图片 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

你现在应该能回答这些问题(检验掌握程度):

  1. npm run serve 和 npm run build 的本质区别?→ 开发态内存编译+热更新 vs 生产态磁盘输出+压缩
  2. vue.config.js 是干嘛的?→ 覆盖 CLI 内置的 webpack 配置
  3. 环境变量为什么要用 VUE_APP_ 开头?→ CLI 白名单,DefinePlugin 文本替换
  4. $router 和 $route 区别?→ 动作 vs 信息
  5. Vuex 里异步操作放哪?→ actions,再 commit 同步的 mutation
  6. 开发环境跨域怎么解决?生产呢?→ devServer 代理 / Nginx 反向代理或 CORS
  7. history 模式刷新 404 为什么?怎么解?→ 服务器没该文件,Nginx try_files 兜底
  8. 打包体积大先干嘛?→ 先用 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 routinesNode 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 mismatchvue 与 vue-template-compiler 版本不一致两个包锁到同一版本号(见 16.2)
Element 按需引入后样式全丢 / Cannot find module 'babel-preset-es2015'插件用错(抄了 babel-plugin-import),或把 Element 官网的 Babel 6 es2015 preset 贴进了 CLI 5Vue 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 项目,你都能快速定位"这个文件/这个配置在这条线的哪一环",这就是工程化思维。接下来最好的学习方式就是:打开你创建的项目,对照本文档,把每一章对应的文件亲自点开看一遍、改一改、重启试试。动手一次,胜过读十遍。

祝学习顺利!🚀