从第一次在官网看到Vue的那句渐进式框架到自己真正上手做完两个项目中间踩过的坑比想象中多得多。这篇笔记是我一边写项目一边记录的产物不打算写得像官方文档那样面面俱到只挑那些真正影响开发效率、容易卡壳的点来讲。如果你正准备入门Vue或者已经写了几个月但总觉得某些概念还悬着这篇笔记应该能帮上忙。1. 环境配置Vue项目的第一步很多新手一开始就倒在环境上不是代码写不明白而是Node.js、脚手架、依赖安装这些乱七八糟的东西没理顺。我整理了一套相对省心的流程照着做基本不会出问题。1.1 Node.js安装与版本选择Vue项目跑起来必须要Node.js这点没得商量。建议直接去官网下载LTS版本不要赶时髦用最新版因为有些依赖包还没跟上最新版的节奏容易出现兼容性问题。安装完之后打开终端输入node -v和npm -v能正常显示版本号就说明装好了。如果提示找不到命令大概率是环境变量没配置好Windows用户检查一下Path里有没有Node.js的安装路径。npm是随Node一起装的包管理器装依赖、启动项目都靠它。但有个问题国内网络环境下载npm包经常慢得让人抓狂于是几乎每个Vue开发者都会用淘宝镜像。配置的方法很简单npm config set registry https://registry.npmmirror.com配好之后再用npm config get registry确认一下显示淘宝镜像的地址就说明生效了。下载速度会明显提升至少不会一个依赖装五分钟。1.2 Vue CLI与Vite的开发体验差异创建Vue项目的工具主要有两个一个是老牌的Vue CLI一个是现在官方主推的Vite。刚接触Vue的人容易纠结选哪个我说下我自己用下来的感受。Vue CLI基于Webpack生态成熟很多老教程和公司的存量项目都在用。启动一个大型项目要十秒甚至更久每次保存代码热更新也要等一两秒说实话有点磨性子。Vite则完全是另一种体验。利用浏览器原生ESModule冷启动基本秒开热更新也快到几乎没有感知。官方文档现在的推荐也是Vite新开项目建议直接用。创建项目的命令也很简单npm create vitelatest my-vue-app -- --template vue装完依赖npm run dev启动浏览器打开localhost端口就能看到默认页面。Vite还有个好处配置文件vite.config.js写起来清爽做路径别名、配置代理都很直观。1.3 第一个项目的启动与目录结构项目创建成功后先别急着写代码把目录结构和各个文件的作用搞清楚后面能省不少事。src目录是日常开发主要打交道的文件夹。main.js是入口文件负责创建应用实例、挂载路由、引入全局插件。App.vue是根组件所有页面的挂载点和全局布局都在这里体现。components放组件router放路由配置views或pages放页面级组件assets放静态资源。组件文件用的是单文件组件写法一个.vue文件里同时包含template、script、style三个部分。这个设计我觉得是Vue很大的一个优点把HTML、JS、CSS收拢到一个文件里组件自带样式和逻辑不会像传统开发那样样式文件满天飞。第一次启动项目建议改一下App.vue看看热更新效果。你会发现改了内容浏览器立刻刷新不需要手动重启。如果Vite没有热更新检查一下是不是改文件的路径在监控范围之外或者编辑器有缓存之类的奇怪问题。2. 路由从基础到动态参数Vue Router是单页应用的核心页面切换、参数传递、权限控制都靠它。这里我把路由相关的知识按使用频率从高到低过一遍重点讲实际操作中容易出错的地方。2.1 路由的基础配置路由配置的核心思路是把路径映射到组件。最基础的方式是在router/index.js里这样写import { createRouter, createWebHistory } from vue-router import Home from ../views/Home.vue const routes [ { path: /, name: home, component: Home }, { path: /about, name: about, component: () import(../views/About.vue) } ] const router createRouter({ history: createWebHistory(), routes }) export default routercomponent有两个写法。直接引用的方式适合基础页面懒加载的箭头函数方式更适合路由较多的项目组件会在路径被访问时才下载首屏加载速度会快不少。createWebHistory是HTML5的History模式地址栏里没有#看起来更清爽但有个前提条件部署到服务器时需要配置try_files规则把不存在的路径都指到index.html否则刷新非首页路径会报404。不想处理服务器配置的话可以改用createWebHashHistory地址会多一个#但胜在省事不需要服务器配合。2.2 动态路由与参数传递动态路由解决的是同一个页面组件根据路径不同展示不同内容的需求典型场景是商品详情页、文章详情页。配置方式是在path里用冒号表示参数{ path: /product/:id, name: product-detail, component: () import(../views/ProductDetail.vue) }获取参数的方式在Vue3的组合式API里是import { useRoute } from vue-router const route useRoute() console.log(route.params.id)很多新手在这里有个误区以为修改参数会触发组件的重新创建。实际上从/product/1跳到/product/2时Vue会复用同一个组件实例created或setup不会重新执行只有watch才能感知到参数变化。所以需要监听route.params在参数变化时重新请求数据。还有一种更灵活的方式是query参数跳转时用router.push({ path: /search, query: { keyword: vue } })接收时用route.query.keyword。query参数的特点是地址栏可读性好适合做搜索条件这类需要分享链接的场景params则适合传递不希望在URL里暴露的数据。2.3 路由守卫与meta配置路由守卫做的是进入页面之前的拦截操作最常见的场景是登录权限校验。Vue Router提供了beforeEach这个全局前置守卫每次路由跳转前都会执行。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next({ path: /login }) } else { next() } })这里的to.meta就是路由配置里的meta字段。可以把需要的元信息都放到meta里比如页面标题、是否需要登录、页面角色权限等。meta里还有个容易被忽视的字段noCache可以配合路由跳转做缓存控制。有些页面不希望被keep-alive缓存比如列表页每次进入都希望重新拉取数据就可以读取to.meta.noCache来判断是否需要清除缓存组件。我还碰到过一个需求动态权限路由。前端登录后拿到用户角色再根据权限动态把路由加进去。实现方式是先定义好所有路由有权限的才通过router.addRoute()添加这样用户没权限的页面即使手动输入URL也进不去。这个方案在实际项目中还挺常见的。3. 组件通信与自定义v-model组件化开发是Vue的底气所在但组件之间怎么传值、怎么通信是很多新手绕不过去的坎。3.1 props与emit父子通信的核心逻辑父子组件通信遵循一个单向数据流原则父组件通过props把数据传给子组件子组件不能直接修改props而是通过$emit发送事件由父组件响应并修改数据。我见过不少新手忍不住想在子组件里直接改props结果控制台报警告页面数据还乱掉。要理解props是只读的这个设计它保证的是数据流向清晰。子组件如果需要根据props衍生出本地数据用computed包一层就行const displayList computed(() props.list.map(item item.name))子组件向父组件通信用的$emitbutton click$emit(update-data, someValue)更新/button父组件监听事件ChildComponent update-datahandleUpdate /这个模式本身不复杂复杂的是多层级嵌套时的透传比如爷孙组件、跨好几个层级的兄弟组件。这种场景下逐层传props和emit会让人写到怀疑人生这时候需要更高阶的方案。3.2 自定义v-model双向绑定的进阶玩法v-model大家用得最多的是对表单元素的绑定但它本质上是modelValue属性和update:modelValue事件的语法糖。理解这一点之后就可以自定义组件的v-model做双向绑定组件。一个典型的例子自定义一个搜索输入框组件父组件用v-model绑定值SearchBox v-modelkeyword /组件内部实现script setup const props defineProps({ modelValue: { type: String, default: } }) const emit defineEmits([update:modelValue]) function handleInput(e) { emit(update:modelValue, e.target.value) } /script template input :valueprops.modelValue inputhandleInput / /template关键的认知是v-model只是语法糖实际做的事是父组件传了一个modelValueprop并且监听了update:modelValue事件。因此组件自己不需要维护内部状态数据始终归父组件管。Vue 3.4之后还推出了defineModel这个宏让自定义v-model的写法简化为const modelValue defineModel()然后直接modelValue.value xxx就行。代码量减少很多但理解背后的原理更重要不然遇到多参数v-model的场景还是会懵。比如一个组件需要绑定多个值价格区间组件的min和max这就需要同时支持v-model:minminPrice和v-model:maxmaxPrice。原理还是一样的只不过每个v-model都对应自己的属性和事件名。3.3 Provide/Inject与跨层级通信当组件嵌套层级很深中间隔着好多不关心这个数据的中间组件用props一层层传递代码会很难看。这时候provide和inject就派上用场了。在祖先组件里provide(theme, theme)在后代组件里const theme inject(theme)但要小心一个问题如果provide传的是响应式数据在Vue3里需要用ref或reactive包一层否则后代组件拿到的是静态值不会跟随变化。还有一种情况是兄弟组件之间通信或者复杂度已经超过父子关系所能表达的建议引入pinia做全局状态管理。虽然有些场景用mitt之类的轻量事件总线也能凑合但项目到了多人协同时期状态管理的规范性和调试方便性是最重要的。Pinia配合DevTools调试体验极好实际工作中用到它的比例非常高。4. 样式处理与特殊场景样式这块看着简单实则有不少细节问题容易让人抓狂。这里记录一下我在实际项目中遇到的几个场景和对应的处理方式。4.1 全局样式与scoped的作用域控制单文件组件里的style scoped是Vue提供的样式隔离机制。加上scoped之后该组件内的样式只对当前组件的元素生效不会污染全局。实现原理并不神秘Vue会给组件内的DOM元素添加一个带有特定>style scoped .parent :deep(.child-inner) { color: red; } /style这是我用了很久才彻底理解的一个点:deep()编译后会去掉作用域限制让样式能穿透到子组件的内部元素。编写全局公共样式时最多的是定义CSS变量、覆盖第三方UI库的默认样式。我习惯把自定义的CSS变量直接放到全局文件里比如主色、文字色、间距等配合Vue模板中的:style绑定使用整个项目的视觉风格能保持得很好。4.2 m3u8视频播放的解决方案现在的项目经常要播放视频尤其是本地视频或局域网视频源格式绕不开m3u8。m3u8是一种基于HTTP Live Streaming的流媒体播放列表格式播放器需要支持HLS协议才能播放。Vue项目里播放m3u8我用的最多的方案是hls.js它通过JavaScript实现HLS播放配合原生video标签使用。安装npm install hls.js播放逻辑import Hls from hls.js const video document.getElementById(video) if (Hls.isSupported()) { const hls new Hls() hls.loadSource(http://example.com/path/to/playlist.m3u8) hls.attachMedia(video) hls.on(Hls.Events.MANIFEST_PARSED, () { video.play() }) }这里有几个关键点要注意。Hls.isSupported()判断浏览器是否支持如果返回false就别硬上提示用户换浏览器更靠谱。loadSource加载的是m3u8地址这个地址必须和页面同源或者服务器设置了跨域头否则会被CORS拦下来。调试跨域问题最常见的现象是视频一直处于加载中状态看请求会报CORS错误。如果用的是video.js播放器也有对应的videojs-contrib-hls插件方案组件化程度更高界面也更好看适合对播放器外观有要求的项目。4.3 移动端适配与360浏览器的兼容移动端适配是另一个痛并快乐着的话题。最常用的做法是在index.html里加viewport meta标签配合Viewport单位的CSS布局。如果用Vant组件库做移动端项目官方推荐配合postcss-pxtorem做px转rem的自动转换设置好根字体大小后不同屏幕宽度下页面元素能按比例缩放。第一次配置完记得看下不同设备上的实测效果字体大小和间距经常需要微调。360浏览器兼容这个事现在基本不用太担心。360安全浏览器和极速浏览器极速模式都是基于Chromium内核Vue3完全兼容。真正需要在意的是企业里可能存在的旧版IE内核兼容需求如果360浏览器的兼容模式解析Vue页面通常会有各种现代语法不兼容的问题。判断方式很简单页面内右键看内核切换选项如果切成兼容模式后页面出现白屏或报错说明代码用了太多不支持ES6的语法。建议让用户使用极速模式访问或者在页面上加提示。5. 调试工具与组合式API的实战经验写Vue项目一个趁手的调试工具能节省大量时间。而组合式API带来的代码组织方式变化也需要一个适应过程。5.1 Vue Devtools的安装与使用技巧Vue Devtools是调试Vue应用的神器能查看组件树、检查props和data、查看Pinia状态、时间旅行调试等。安装方式推荐用Chrome或Edge的扩展商店直接搜索下载版本要和实际使用的Vue版本匹配。Vue2老项目对应的是Vue.js devtools v6版本Vue3项目要安装支持Vue3的版本。下载好插件但页面里Vue Devtools图标是灰色通常有两个原因。一是页面没有运行Vue应用打开一个Vue页面就能检测到二是页面运行的是生产环境构建的VueVue2需要开发构建版本才能被检测到Vue3默认可以。如果是Electron、App内嵌WebView这类非浏览器环境调试还可以用vue-devtools远程调试方案通过远程连接调试端口。用Vue Devtools最有价值的功能之一是时间旅行调试可以回放每次状态变更前后组件的状态定位Bug到底是哪一步状态突变导致的极大提升排查效率。这个工具一开始就要养成用的习惯不然等系统复杂了再开始用会很不适应。5.2 组合式和选项式API混用Vue3虽然主推组合式API但很多老项目是选项式API写的新项目里也经常需要混用。我实际开发中啥情况都见过需要说明的是两种API完全可以共存同一个组件既可以写setup()也可以写data、methods等选项。一个常见的混用方式是在选项式组件里调用setup()利用setup里返回的变量和方法配置到组件模板里直接用。也有反过来用的在组合式API的setup里调用组件的选项式属性可以通过getCurrentInstance()拿到组件实例进而访问this.$options里的钩子数据。混用开发的实际体验核心原则是逻辑复用优先用组合式API简单组件的模板逻辑用选项式API写起来也顺手。不用纠结一定要用什么能解决问题就行。5.3 自定义指令自定义指令是Vue少有人深挖但实际非常好用的功能适合处理那些模板里写逻辑太啰嗦写在组件方法里又不够通用的场景。比如点击外部区域关闭弹窗、页面滚动加载更多、自动聚焦输入框都可以用自定义指令封装。注册方式const vFocus { mounted: (el) el.focus() } // 全局注册 app.directive(focus, vFocus)页面里input v-focus /指令的生命周期钩子和组件类似有created、mounted、updated、unmounted等。最常用的还是mounted指令挂载到DOM后立刻执行。做权限控制时我通常用自定义指令封装一个检查权限的函数无权限时直接移除DOM节点这样权限控制的逻辑就不会散落到各个组件里。自定义指令的难点在于理解el参数是真实的DOM元素你可以直接操作DOM这在Vue声明式开发的语境下容易让人不适应。但恰恰是这种底层能力让自定义指令能处理那些纯模板语法解决不了的需求。6. 常见问题排查速查表开发Vue项目这段时间我把容易遇到的高频问题整理成了一表。自己在项目中踩过也帮同事排查过不少按表索骥基本能解决大部分日常问题。问题现象可能原因排查思路npm install超时或失败网络原因或依赖冲突切换到淘宝镜像删除node_modules和lock文件重新安装路由跳转后组件不刷新复用了同一个组件实例使用watch监听路由参数变化或给router-view加:keyCannot read property of undefined尝试读取不存在的数据属性优先检查后端数据是否返回用?.可选链或v-if兜底控制台警告props修改子组件直接修改了props用emit事件通知父组件或改用computed派生数据样式不生效scoped导致选择器权重不对用:deep()穿透或提高选择器层级图片资源404路径没有经过构建配置处理使用require或import引入本地资源不要用相对路径写死m3u8无法播放跨域或编码问题检查请求的CORS响应头测试不同编码的播放源window is not defined浏览器API在服务端或构件环境被调用确认代码只在onMounted等浏览器生命周期中调用打包后刷新404History模式路由未配置服务器规则配置nginx的try_files指向index.html或改用Hash模式排查问题有个很实用的习惯先看浏览器控制台报什么错再点进去看具体报错的代码文件和行号。Vue的报错信息其实相当友好大部分把关键信息都告诉你了很多人只是没耐心看而已。6.1 依赖安装与版本冲突Vue项目里的依赖管理版本冲突是很磨人的一件事。最常见的场景是A包依赖vue2B包依赖vue3两者同装必然冲突。遇到这种问题我的建议第一是去看项目根目录的package.json确认锁定的版本。如果项目在推进过程中从旧版本升级先跑npm outdated查各依赖的更新状态。解决方案通常有几个升级不兼容的依赖到支持Vue3的版本、使用npm dedupe去重、或者用pnpm的依赖隔离机制处理不同版本的重复依赖。还有一类坑是仅检查报错不检查安装日志。有些报错的前置原因是某个依赖安装失败只是没仔细看输出。安装时建议把终端输出滚动完关键字看到ERR!、WARN deprecated、ELIFECYCLE都要重视起来。6.2 项目实战中的一个综合案这里分享一个后台管理系统的案例。需求是做一个实验室设备管理系统Vue3 Spring Boot前后端分离路由大概有十多个还需要根据角色控制页面权限。整个项目的架构是前端Vue3 Vite路由用createWebHistoryPinia做状态管理页面组件全用懒加载。后端Spring Boot提供API接口前端通过axios请求。联调之后发现问题集中在两处一是路由刷新404nginx里配置了try_files解决二是登录状态刷新丢失用Pinia持久化插件把token存进localStorage解决。权限控制那边跟后端商量了动态路由方案后端返回角色对应的路由名称数组前端通过router.addRoute动态注册菜单也根据权限动态生成。这个方案有个细节值得分享就是退出登录要把动态添加的路由全部清理掉否则换个账号登录后菜单还残留着上一个账号的权限处理方式是用router.getRoutes()把动态路由逐条移除。这套项目里还用到了企业微信JS-SDK。这个我简单提一句在Vue项目里用wecom/jssdk需要先通过后端获取签名配置前端再调用config接口注入配置。这里有个容易踩的坑是timestamp和nonceStr一般是由后端生成前端只做透传签名用的URL必须和当前页面的完整URL完全一致不能带多余的参数否则签名校验会失败。6.3 一个容易忽视的调试场景如果你在做Electron Vue的项目会遇到主进程和渲染进程的通信问题。调试时发现页面里的Vue实例是正常的数据流动也没问题但调用Electron的API时总是不生效根因往往是主进程和渲染进程的上下文没有对上。ipcMain和ipcRenderer的通信要理清事件名的唯一性两边写的channel必须完全一致大小写都不能差。写代码时顺手把channel名称定义成一个常量文件两边都引用同一份这个失误就能完全避免。Vue本身跟Electron没有直接关系Vue只是负责渲染进程里的界面框架而Electron的进程模型属于另一个体系。把这两件事分开理解就不会傻傻地在Vue组件里直接调Node.js的API了。这个内容后续还可以扩展的方向挺多比如Vue3的源码阅读、渲染函数的实现原理、响应式数据的依赖追踪机制这些搞懂之后能更好地理解框架在做什么。不过先把手头项目做利索再回头啃源码效果要好得多。