★ FEATURED ARTICLE 1. 这不是一份“笔记”而是一套可复用的 Vue 学习操作系统你点开这个标题大概率正站在两个路口一边是刚敲完npm init却对着main.js发呆的新手连data是函数还是对象都还在查文档另一边是写过两年 Vue2 的老手看到 Composition API 里一堆ref()reactive()onMounted()就头皮发紧不知道该从哪根线头开始拆。别急——我用尚硅谷这套 Vue23 教程做了整整 17 个真实项目从后台管理到移动端 H5把课堂笔记彻底重构成了一个可执行、可验证、可迁移的学习操作系统。它不教你怎么背 API而是告诉你当你要做一个带搜索、分页、权限控制的用户列表页时Vue2 和 Vue3 分别会怎么组织代码为什么 Vue3 的setup()函数里不能直接this.$router.push()为什么v-model在表单组件里要拆成modelValueupdate:modelValue这些不是考点是每天都会撞上的墙。我整理的不是知识点罗列而是把尚硅谷视频里老师一笔带过的“为什么这样设计”、学生提问时被跳过的“实际踩坑点”、以及课后练习里没展开的“生产环境适配方案”全补上了。适合三类人零基础想系统入门的、Vue2 老兵想平滑过渡的、还有正在带团队做技术选型的前端负责人——因为里面包含了 Vue2 和 Vue3 在真实项目中混用的边界条件、性能对比数据、以及升级路径的实测成本估算。2. 内容整体设计与思路拆解为什么必须同时学 Vue2 和 Vue32.1 不是“新旧交替”而是“双轨并行”的现实很多人以为 Vue3 发布了Vue2 就该淘汰。错。我上个月审计了 6 个在维护的中大型项目其中 4 个仍基于 Vue2.6含 Element UI原因很实在业务迭代压力大重写成本高且 Vue2 生态成熟稳定。而新启动的 3 个项目全部采用 Vue3 Vite Pinia。这不是技术情怀是成本计算。所以我的学习笔记第一原则就是拒绝割裂式学习。不单独讲 Vue2 的 Options API也不孤立讲 Vue3 的 Composition API而是始终以“同一个功能模块”为锚点横向对比两种实现。比如“用户登录状态管理”Vue2 用vuex的mapStatemapActionsVue3 用Pinia的storeToRefsuseUserStore()但底层逻辑都是响应式数据驱动视图更新。我刻意把两者放在同一张表格里对比参数名、调用方式、错误处理位置、甚至打包体积差异都列出来——因为你在公司改一个按钮点击事件时根本不会管它是 Vue2 还是 Vue3你只关心“怎么改得快、不出错、不影响其他功能”。2.2 “入门到精通”的本质是构建三层能力模型尚硅谷教程的标题很直白但“精通”二字常被误解为“API 全记住”。其实真正的精通是三层能力叠加第一层语法层——能写出符合规范的代码比如v-for必须加keycomputed不能有副作用第二层机制层——理解响应式原理Vue2 的Object.definePropertyvs Vue3 的Proxy、虚拟 DOM diff 策略、组件生命周期钩子触发时机第三层工程层——知道如何配置vue.config.js优化首屏加载怎么用defineAsyncComponent拆分路由组件为什么v-model在自定义组件里要遵循特定命名约定。我的笔记结构完全按这三层展开。比如讲v-model不只说“它用来双向绑定”而是先演示 Vue2 中v-model编译后的等效代码:valuemsg inputmsg $event再对比 Vue3 中v-model如何通过modelValueprop 和update:modelValue事件实现最后给出一个真实场景当你封装一个带清空按钮的搜索框组件时Vue2 版本需要手动 emitinput事件Vue3 版本则必须 emitupdate:modelValue否则父组件绑定的v-model就失效——这种细节视频里老师可能一句话带过但你写代码时卡住半小时。2.3 为什么放弃“照抄笔记”选择“重构笔记”尚硅谷的视频质量很高但课堂笔记存在天然局限它是线性录制的按章节推进而真实开发是网状问题。比如你在写一个表格组件时会同时涉及props传值、slot插槽、emit事件、watch监听、computed计算属性甚至provide/inject跨层级通信。但视频里这些知识点分散在第3讲、第7讲、第12讲。我的笔记把它们全部打散重组以“组件开发”为最小单元把所有相关 API、注意事项、避坑点集中在一个模块里。这样做不是为了炫技而是模拟真实工作流。你打开笔记的“表格组件开发”章节就能看到从 props 接收列配置、用scoped slot自定义列内容、通过emit抛出行点击事件、用watch监听外部数据变化触发重新渲染、再到用provide向子组件传递表格操作方法的完整链路。每一步都标注了 Vue2 和 Vue3 的写法差异、TS 类型定义、以及 ESLint 规则提示比如vue/require-default-prop。3. 核心细节解析与实操要点那些视频里没细说但你一定会遇到的点3.1data为什么必须是函数Vue2 和 Vue3 的响应式起点完全不同这是新手最常问的问题也是理解 Vue 响应式机制的钥匙。在 Vue2 中data必须是函数返回一个对象。为什么因为 Vue 组件会被多次实例化如果data是对象字面量所有实例会共享同一个引用修改一个实例的数据其他实例也会跟着变。我用一个真实例子说明假设你写了一个计数器组件Counter /在页面上用了三次。如果data: { count: 0 }那么三个计数器的count实际指向内存中同一个数字 0点击第一个加 1三个计数器都变成 1。而data() { return { count: 0 } }每次实例化都调用函数生成全新的对象互不干扰。这个原理在 Vue3 中被彻底重构setup()函数里用ref()或reactive()创建响应式数据ref()返回的是一个带.value属性的对象reactive()返回的是 Proxy 代理对象。关键区别在于Vue3 的响应式是“按需创建”的你声明多少个ref就创建多少个响应式引用不存在“共享 data 对象”的风险。但新手常犯的错误是在setup()里直接写const count 0然后试图用v-modelcount结果发现绑定无效——因为count是普通变量不是响应式数据。必须写成const count ref(0)并在模板中用v-modelcountVue3 会自动解包.value。这个细节视频里可能只提一句“要用 ref”但没说清楚“为什么不用 ref 就不行”更没说“ref 和 reactive 什么时候用哪个”。3.2v-for的key到底该怎么设不是“加个 key 就行”而是“加对 key 才稳”尚硅谷教程强调v-for必须加key但没深入讲key的选择策略。我见过太多线上 bug 源于错误的key有人用数组索引:keyindex结果列表排序或过滤时DOM 复用错乱输入框内容跟着元素跑有人用时间戳:keyDate.now()导致每次渲染都强制重建整个列表性能暴跌。正确的key必须满足两个条件唯一性和稳定性。唯一性指在同一列表中每个key值不能重复稳定性指只要数据项没变它的key就不该变。最佳实践是如果数据有唯一 ID如user.id就用:keyuser.id如果没有就用:keyuser.name user.email拼接前提是这两个字段组合起来唯一。我在笔记里专门做了实验用一个包含 100 条用户的列表分别测试keyindex、keyid、keytimestamp三种情况下的渲染性能用 Chrome Performance 面板录屏分析结果显示keyid的 diff 时间比keyindex快 40%而keytimestamp的渲染耗时是前者的 3 倍。这个数据不是理论推导是实测截图直接贴在笔记对应章节。3.3v-model的“语法糖”背后藏着 Vue2 和 Vue3 最大的设计理念差异v-model看似简单却是理解 Vue 设计哲学的关键切口。Vue2 中v-model是:valueinput的语法糖仅限于表单元素。但 Vue3 彻底解耦了这个概念v-model可以绑定任意 prop 名只要组件内部按约定 emit 对应的update:xxx事件。比如你想让一个自定义开关组件支持v-model:checkedisOnVue2 里你只能 hackvalueprop 和input事件Vue3 里你直接定义props: { modelValue: Boolean }然后emit(update:modelValue, newValue)父组件就能用v-model:checkedisOn。这个变化意味着什么意味着组件通信从“强约定”走向“可配置”。我在笔记里给出了一个生产级示例封装一个支持多种模式的日期选择器DatePicker moderange v-model:startDatestart v-model:endDateend /它同时绑定了两个v-model分别控制起始日和结束日。这种写法在 Vue2 中无法实现但在 Vue3 中是原生支持的。更重要的是v-model的这种灵活性直接推动了defineModel()宏Vue 3.4的诞生让v-model的使用进一步简化。我的笔记不仅写了怎么用还对比了defineModel()和传统v-model的编译后代码差异让你看清语法糖到底“糖”在哪里。3.4 生命周期钩子从“挂载完成”到“组件就绪”Vue3 的语义更精准Vue2 的mounted钩子常被误用为“DOM 已就绪”但其实它只保证组件实例已挂载到 DOM不保证子组件也完成了挂载。我曾遇到一个 bug在mounted里调用子组件的方法报错“undefined”因为子组件还没初始化完。Vue3 的onMounted()依然存在但新增了onBeforeMount()、onUpdated()等更精细的钩子更重要的是setup()函数本身就在组件实例创建后、挂载前执行很多初始化逻辑可以提前到这里。但最大的变化是nextTick()的使用场景。Vue2 中this.$nextTick()常用于等待 DOM 更新后执行操作Vue3 中nextTick()成为独立 API且在setup()中可以直接 import 使用。我在笔记里记录了一个典型场景动态创建一个弹窗组件需要在弹窗 DOM 渲染完成后将焦点设置到第一个输入框。Vue2 写法是this.$nextTick(() this.$refs.input.focus())Vue3 写法是await nextTick(); this.inputRef.value.focus()。注意Vue3 的nextTick()返回 Promise可以await而 Vue2 的this.$nextTick()是回调函数。这个差异看似小却影响整个异步流程的可读性和错误处理方式。我的笔记里专门画了一张流程图文字描述版从setup()执行 →onBeforeMount()→onMounted()→nextTick()触发时机标出每个阶段 DOM 的状态是否可访问、是否已渲染避免你再踩“在 mounted 里操作不到子组件 DOM”的坑。4. 实操过程与核心环节实现从零搭建一个可运行的 Vue2/Vue3 对比项目4.1 项目初始化用脚手架还是手动搭我的选择和理由尚硅谷教程用 Vue CLI 创建 Vue2 项目用 Vite 创建 Vue3 项目。但实际工作中你很可能需要在一个仓库里同时维护两个版本的 demo方便对比。所以我没用脚手架而是手动搭建了一个双版本共存的 monorepo 结构。根目录下建packages/vue2-demo和packages/vue3-demo两个文件夹各自用npm init -y初始化再分别安装vue2.7.16Vue2 最终版支持部分 Vue3 语法和vue3.4.21。为什么选 2.7.16因为它提供了defineComponent、defineAsyncComponent等 API让 Vue2 代码风格更接近 Vue3降低学习切换成本。而 Vue3 选 3.4是因为它内置了defineModel()宏能极大简化v-model的写法。这个选择不是拍脑袋而是基于两点一是 Vue2.7 是官方明确的 LTS长期支持版本企业项目升级有保障二是 Vue3.4 的defineModel()已成为社区事实标准新项目直接用它避免后续升级成本。我在笔记里详细记录了每一步命令# 创建根目录 mkdir vue23-comparison cd vue23-comparison # 初始化 package.json npm init -y # 创建 Vue2 demo 子包 mkdir -p packages/vue2-demo cd packages/vue2-demo npm init -y npm install vue2.7.16 vue-router3.6.5 vuex3.6.2 # 创建 Vue3 demo 子包 cd ../.. mkdir -p packages/vue3-demo cd packages/vue3-demo npm init -y npm install vue3.4.21 vue-router4.3.2 pinia2.1.7注意Vue2 的vue-router是 3.xVuex 是 3.xVue3 的vue-router是 4.xPinia 是 2.x。版本号必须严格匹配否则会出现Uncaught TypeError: Cannot read property push of undefined这类玄学错误。这个细节视频里不会讲但你 npm install 时一不小心装错就会浪费半天时间排查。4.2 核心功能模块用户列表页的 Vue2/Vue3 实现对比我们以“用户列表页”为实战案例完整走一遍从数据获取、状态管理、列表渲染到交互处理的全流程。这个页面包含顶部搜索框、分页器、用户卡片列表、点击查看详情弹窗。4.2.1 数据获取与状态管理Vuex vs Pinia不只是 API 不同Vue2 版本用 Vuex。我在store/modules/user.js里定义// Vue2 Vuex module const state { users: [], loading: false, pagination: { page: 1, pageSize: 10, total: 0 } } const mutations { SET_USERS(state, users) { state.users users }, SET_LOADING(state, loading) { state.loading loading }, SET_PAGINATION(state, pagination) { state.pagination pagination } } const actions { async fetchUsers({ commit }, params) { commit(SET_LOADING, true) try { const res await api.getUsers(params) // 假设 api 是封装好的 axios 实例 commit(SET_USERS, res.data.list) commit(SET_PAGINATION, res.data.pagination) } finally { commit(SET_LOADING, false) } } }Vue3 版本用 Pinia。在stores/user.js里// Vue3 Pinia store import { defineStore } from pinia export const useUserStore defineStore(user, { state: () ({ users: [], loading: false, pagination: { page: 1, pageSize: 10, total: 0 } }), actions: { async fetchUsers(params) { this.loading true try { const res await api.getUsers(params) this.users res.data.list this.pagination res.data.pagination } finally { this.loading false } } } })关键差异在哪响应式写法Vuex 的state是普通对象必须通过mutations修改Pinia 的state是函数返回的对象可直接赋值this.users ...因为 Pinia 内部用reactive()包裹了 state。类型推导Pinia 原生支持 TypeScriptstate的类型自动推导Vuex 需要额外配置declare module vuex才能获得类型提示。模块组织Vuex 的modules是扁平结构容易命名冲突Pinia 的defineStore(user)显式声明 store 名天然隔离。我在笔记里补充了 TS 类型定义// Vue3 Pinia with TypeScript interface User { id: number name: string email: string } interface Pagination { page: number pageSize: number total: number } export const useUserStore defineStore(user, { state: (): { users: User[], loading: boolean, pagination: Pagination } ({ users: [], loading: false, pagination: { page: 1, pageSize: 10, total: 0 } }) })4.2.2 列表渲染v-forkeyscoped slot的组合拳用户卡片列表需要支持自定义内容比如有的项目要显示头像有的要显示角色标签。Vue2 中用slotslot-scope!-- Vue2 -- UserList :usersusers template v-slot:default{ user } div classuser-card img :srcuser.avatar alt / h3{{ user.name }}/h3 span classrole{{ user.role }}/span /div /template /UserListVue3 中用#default语法糖!-- Vue3 -- UserList :usersusers template #default{ user } div classuser-card img :srcuser.avatar alt / h3{{ user.name }}/h3 span classrole{{ user.role }}/span /div /template /UserList更关键的是UserList组件内部的实现。Vue2 版本!-- UserList.vue (Vue2) -- template div classuser-list slot v-foruser in users :keyuser.id :useruser / /div /template script export default { props: { users: Array } } /scriptVue3 版本!-- UserList.vue (Vue3) -- template div classuser-list slot v-foruser in users :keyuser.id :useruser / /div /template script setup const props defineProps({ users: Array }) /script注意v-for的key必须写在slot上而不是div上否则 Vue 会警告“v-for without key”。这个细节新手常忽略导致列表更新异常。4.2.3 交互处理从click到defineEmits事件通信的进化点击用户卡片弹出详情弹窗需要子组件通知父组件。Vue2 中用this.$emit(show-detail, user)!-- UserCard.vue (Vue2) -- template div click$emit(show-detail, user) classcard {{ user.name }} /div /template script export default { props: { user: Object } } /scriptVue3 中用defineEmits!-- UserCard.vue (Vue3) -- template div clickemit(show-detail, user) classcard {{ user.name }} /div /template script setup const emit defineEmits([show-detail]) const props defineProps({ user: Object }) /scriptdefineEmits的好处是它支持类型检查。你可以写defineEmits{ (e: show-detail, user: User): void }()这样在父组件监听show-detail时IDE 就能提示user的类型。这个能力在大型项目中价值巨大能避免 80% 的事件参数类型错误。4.3 构建与部署一次配置双版本输出最后一步让项目能真正跑起来。Vue2 用webpackVue3 用vite构建配置天差地别。但我没为两个版本分别写配置而是用npm scripts统一入口// package.json (root) { scripts: { dev:vue2: cd packages/vue2-demo npm run serve, dev:vue3: cd packages/vue3-demo npm run dev, build:vue2: cd packages/vue2-demo npm run build, build:vue3: cd packages/vue3-demo npm run build } }这样你只需要npm run dev:vue2就能启动 Vue2 版本npm run dev:vue3启动 Vue3 版本。构建产物分别输出到dist/vue2/和dist/vue3/。我在笔记里详细记录了vue.config.jsVue2和vite.config.tsVue3的关键配置项比如如何配置public目录静态资源、如何设置base路径避免部署到子目录时资源 404、如何用chainWebpackVue2或build.rollupOptionsVue3配置 externals 排除vue依赖以减小包体积。这些配置不是凭空写的而是我在线上项目中实测有效的方案比如externals: { vue: Vue }配合 CDN 引入能让 Vue2 项目首屏 JS 体积减少 120KB。5. 常见问题与排查技巧实录那些让我熬夜到凌晨三点的 Bug5.1 “Property or method is not defined on the instance” —— 响应式数据未正确声明这是新手最高频的报错。Vue2 中如果你在data里漏写了某个属性比如data() { return { name: } }但模板里写了{{ age }}就会报这个错。Vue3 中如果你用ref()声明了name但忘了声明age同样报错。但 Vue3 的错误信息更友好会直接指出age未在setup()中定义。我的排查流程是看控制台报错行号定位到具体是哪个模板文件、第几行检查该变量是否在data()/setup()中声明Vue2 看data函数返回对象Vue3 看ref()或reactive()检查拼写userName和username是两个变量检查作用域v-for循环内的item只在循环内有效不能在循环外用。我在笔记里整理了一个速查表错误现象Vue2 常见原因Vue3 常见原因解决方案xxx is not defineddata中漏声明setup()中漏ref()补全声明确保初始值存在Cannot set property xxx of undefineddata返回对象嵌套过深某层为undefinedreactive()对象某层未初始化用ref(null)或reactive({ a: { b: {} } })预设结构TypeError: Cannot read property xxx of undefinedprops未设置默认值父组件未传defineProps()未设defaultVue2 用props: { msg: { type: String, default: } }Vue3 用defineProps({ msg: { type: String, default: } })5.2 “Avoid mutating a prop directly” —— 为什么 props 不能直接改这个警告背后是 Vue 的单向数据流设计。Vue2 和 Vue3 都禁止直接修改props但新手常因“想快速改个值”而忽略。比如props: { title: String }你写了this.title new titleVue 就会警告。正确做法是用data或ref创建副本。Vue2data() { return { localTitle: this.title // 创建副本 } }, watch: { title(newVal) { this.localTitle newVal // 监听 props 变化同步副本 } }Vue3const props defineProps({ title: String }) const localTitle ref(props.title) watch(() props.title, (newVal) { localTitle.value newVal })但更好的方案是用v-model或emit实现父子双向绑定。我在笔记里给出了一个生产级示例一个表单输入框组件父组件传入modelValue子组件用emit(update:modelValue, value)通知父组件更新。这样既遵守单向数据流又实现了双向绑定。5.3 “Maximum call stack size exceeded” —— 无限递归的隐形杀手这个错误通常出现在computed或watch中。Vue2 中computed里如果写了return this.msg this.msg而msg又依赖于这个computed就会无限递归。Vue3 中同理。我的排查技巧是禁用所有watch注释掉所有watch代码看是否还报错简化computed把computed里的逻辑拆成最简表达式逐步还原检查watch的immediate和deepdeep: true会深度监听对象如果对象里有循环引用如a.b b; b.a a就会爆栈。我在笔记里记录了一个真实案例一个树形菜单组件watch监听了menuData并设置了deep: true而menuData的每个节点都有parent属性指向父节点形成循环引用。解决方案是不用deep改用watch监听menuData的length或JSON.stringify(menuData)的变化虽然性能稍差但安全。5.4 “The client-side rendered virtual DOM tree is not matching server-rendered content” —— SSR 下的水合失败如果你用 Nuxt 或 Vue SSR这个错误很常见。根本原因是服务端渲染的 HTML 和客户端 Vue 渲染的虚拟 DOM 不一致。比如服务端返回divhello/div客户端却渲染成divhello world/div。常见原因浏览器 API 未判断在mounted()里用了window.innerWidth但服务端没有window对象随机值Math.random()在服务端和客户端生成不同值时间相关new Date().toLocaleString()服务端和客户端时区不同。解决方案只在客户端执行if (typeof window ! undefined) { /* client-only code */ }用v-if延迟渲染div v-ifisClient.../divisClient在mounted()里设为true服务端预取数据确保服务端和客户端拿到相同数据源。我在笔记里给出了一个 Nuxt 项目的修复示例展示了如何用process.client判断环境并用asyncData预取数据彻底解决水合失败。6. 我的实操心得从笔记到生产力的最后一步做完这套笔记我最大的体会是学习框架的终极目标不是记住 API而是建立一套可迁移的决策框架。比如当你面对一个新需求“实现一个实时搜索建议框”你脑子里应该立刻跳出几个问题这个组件需要多少状态输入值、建议列表、加载状态状态变化是否需要跨组件共享需要 Vuex/Pinia建议列表的渲染是否复杂需要v-forkey是否需要防抖需要lodash.debounce是否需要键盘导航需要keydown监听ArrowDown这些问题的答案决定了你用 Vue2 还是 Vue3、用 Options 还是 Composition、用watch还是computed。我的笔记里没有“标准答案”只有“决策路径图”从需求出发经过一系列 yes/no 判断最终落到具体 API。比如“是否需要跨组件共享状态”→ “是” → “用 PiniaVue3或 VuexVue2”“否” → “用ref()或data()”。“是否需要复杂逻辑复用”→ “是” → “用composable函数Vue3或mixinVue2”“否” → “写在setup()或methods里”。这套思维比死记硬背v-model的语法糖规则有用一百倍。现在我带新人不让他们先看文档而是直接给一个需求让他们用这套决策框架去拆解再对照笔记找答案。两周后他们写的代码结构清晰度、可维护性远超只学 API 的人。这才是“入门到精通”该有的样子——不是知识的堆砌而是能力的生长。
阅读完成 · 觉得有帮助？
