1. 从脚手架到指令Vue 入门到底要先啃哪块搞 Vue 的人手机里、收藏夹里、博客里多少都会存一份类似“Vue核心指令全集”的速查笔记。要说起来Vue 这东西本身不难难的是你拿到一个真实项目时看到 template 里挤满了v-if、v-for、v-on、v-model一时间不知道该先看哪个、改哪个、删哪个。这篇文章我就从这个标题展开把脚手架、模板渲染、属性绑定、事件处理、条件渲染、列表循环、双向绑定这一整套串起来讲一遍。不管你是在公司刚接手一个 Vue2 老项目还是打算用 Vite 从零搭一个 Vue3 新项目这套东西都是绕不开的地基。先明确一个事实Vue 的核心是“声明式渲染”意思是你告诉框架“页面长什么样”框架负责把数据变成 DOM。而上面这一串指令就是你声明逻辑时使用的语法工具。脚手架是用来建的房子指令是房子里的水电布线两者配合起来才是一套能住的工程。适合谁来读刚学完 HTML/CSS/JavaScript 想入门 Vue 的前端新手写过一点 Vue 但指令之间区别模糊、经常混用的初中级开发者准备面试、想系统梳理 Vue 基础考点的同学。这篇文章偏实战我会把每个指令的“为什么”讲清楚再给你能直接复制的代码段。先说结论再逐步拆解。2. 脚手架为什么必须用以及到底怎么搭2.1 从 CDN 引 Vue 和用脚手架到底差在哪很多新手第一步是去官网复制script srcvue.global.js然后写个hello.html。这样做没错它适合体验语法但一旦项目复杂起来CDN 方案会立刻暴露三个问题模块化困难、开发体验差、无法使用单文件组件。单文件组件SFC即.vue文件是 Vue 工程化的灵魂它把模板、脚本、样式写在一个文件里。CDN 方案里没有编译环节浏览器不认识.vue文件所以你必须借助构建工具。脚手架说白了就是“帮你把构建工具链配置好”的架子。我建议新手直接上脚手架不要在 CDN 方案里停留太久。这不是说 CDN 没用而是工程化是现实团队协作的基本盘。你早点熟悉脚手架的目录结构和构建流程后面接手任何中大型项目都不会慌。2.2 目前主流的脚手架创建方式现在是 2025 年Vue 官方推荐的创建方式已经全面转向 ViteVue CLI基于 Webpack虽然还在维护但已经进入维护模式。Vite 的核心优势是极速冷启动——它利用浏览器原生 ESM 按需编译而不是像 Webpack 那样先打包再启动。创建项目只需要一条命令npm create vuelatest执行后命令行会问你几个问题项目名称、是否使用 TypeScript、是否引入 Vue Router、Pinia、Vitest、ESLint 等。对新手来说建议先全选 No等熟悉了基础再逐步加入。我见过不少人一上来就勾了一堆功能结果连目录结构都看不懂反而被劝退了。npm install npm run dev这两条命令分别是安装依赖和启动开发服务器。跑起来之后浏览器打开http://localhost:5173就能看到页面。项目根目录下有vite.config.js很多基础配置都在这改比如开发服务器端口、路径别名、代理转发等。2.3 脚手架目录结构里藏着哪些信息一个标准 Vue3 Vite 项目的基本结构如下├── index.html ├── package.json ├── vite.config.js ├── public ├── src │ ├── main.js │ ├── App.vue │ ├── components │ ├── router │ ├── stores │ └── viewsmain.js是入口文件它负责创建应用实例、挂载根组件。App.vue是根组件它的子组件由路由或手动挂载渲染。components放通用组件views放页面级组件。这个结构不是死的但它是官方默认的合理约定你最好不要乱改。脚手架帮你搞定的核心事情有三个编译.vue文件、处理模块依赖、提供热更新HMR。热更新的意思是你改完保存页面不用刷新改动直接生效。开发体验对幸福感的影响真的很大。注意npm create vuelatest创建的默认模板非常干净没有vue.config.js这类老项目里的文件。如果你想配代理、配路径别名改的是vite.config.js。如果你接手的是老项目Vue CLI 体系那改的是vue.config.js。两个文件名别搞混。3. 渲染内容v-text、v-html 的用法与安全边界3.1 v-text 和插值表达式几乎等价v-text的语义是“把这个元素的文本内容替换成表达式的值”。它的写法和插值表达式{{ }}高度相似但有一个关键区别v-text会覆盖元素内部原有的内容而插值表达式只在所在位置插入内容。template div v-textmessage/div div{{ message }}/div /template大部分情况下你可能根本用不到v-text因为插值表达式更灵活。v-text存在的价值主要是两个场景一是当你想彻底控制某个区域的渲染内容不希望被其他文本干扰时二是在某些需要手动拼接字符串的边界场景里。3.2 v-html 能渲染 HTML也能把你坑哭v-html的作用是渲染真正的 HTML 字符串。比如后台返回了一段富文本strong加粗/strong你用插值表达式只会看到这段字符串本身用v-html才能让浏览器渲染出加粗效果。template div v-htmlrenderedContent/div /template script setup const renderedContent p stylecolor: red;这段文字是红色的/p /script能渲染 HTML 就意味着能执行脚本。v-html所渲染的内容如果来自用户输入那就是典型的 XSS 注入入口。你可以自己试一下把renderedContent改成img srcx onerroralert(攻击成功)页面会直接弹窗。我的建议很明确不要对用户输入的内容使用v-html。后台返回的富文本你需要在服务端做好清洗过滤前端再做一层转义兜底。否则哪天运营上传了一段带脚本的文案你的页面就会成为钓鱼链接分发器这不是危言耸听。3.3 这两个指令和插值表达式的选型原则日常开发中优先级排序是插值表达式 v-text v-html。能用插值表达式解决的不要用 v-text能不用 v-html 的坚决不用。我自己在实际项目中v-html的使用率非常低几乎只用在“渲染富文本详情页”和“渲染后端返回的 HTML 片段”这两个场景。而且我们会在后端配合做安全策略把危险标签和属性在源头过滤掉。注意不要在v-html的内容里拼接用户 ID、手机号、昵称等动态数据。如果你一定要拼把这些字段做 encode 处理后再拼进 HTML 字符串。4. 属性绑定与事件绑定v-bind 和 v-on 的组合拳4.1 v-bind让属性值“活”起来HTML 属性默认是写死的img srclogo.png。如果你想让 src 的值跟随数据变化你就需要v-bind。基本的写法是v-bind:srcimgSrc也常用简写:srcimgSrc。template img :srcuserAvatar alt用户头像 a :hrefarticleUrl文章链接/a div :classactiveClass绑定 class/div /template:class和:style是两个比较特殊的情境。:class可以绑定字符串、数组、对象三种形式。对象形式在业务中非常常见它表示“类名是否生效取决于某个布尔值”。template div :class{ active: isActive, disabled: isDisabled }状态样式/div /template script setup const isActive true const isDisabled false /script数组形式适合同时应用多个类名比如基础样式加状态样式。对象数组混用也可以Vue 会帮你拍平。4.2 v-on绑定事件但要小心 thisv-on用来监听 DOM 事件简写是。比如clickhandleClick、inputhandleInput、submit.preventhandleSubmit。template button clickcount点击 1/button button clickhandleIncrement(2)点击 2/button /templatev-on的表达式可以是一个方法名、一个内联语句甚至一个简单的赋值表达式。这就带来一个容易踩坑的问题在模板里直接用this是拿不到组件实例的至少在 Vue3 的script setup布局里不是这样心智模型。所以建议统一把逻辑写进方法模板里只做“触发动作”和“传参”两件事。v-on有事件修饰符比如.stop阻止冒泡、.prevent阻止默认行为、.once只触发一次、.enter监听回车键。看一个例子template form submit.preventhandleSubmit input typetext keyup.entersearch button typesubmit提交/button /form /template.prevent等价于e.preventDefault()。在表单提交场景下你不用在方法内部再手动调一次 prevent代码会干净很多。4.3 v-bind 和 v-on 一起出现:value 和 input 的组合这两个指令组合起来就是后面要讲的 v-model 的原理。手动理解这个组合非常重要因为 v-model 只是它们的一个语法糖。看这段代码template input :valuename inputname $event.target.value /template:value把name数据绑定到输入框的显示值input监听用户的输入并把最新的值写回name。二者配合就实现了数据的双向同步。如果你理解了这句话v-model 的原理你就掌握了八成。5. 条件渲染v-show、v-if 怎么选才不浪费性能5.1 最直白的区别display:none 和真正的销毁/重建v-show控制元素显示还是隐藏本质上只是切换 CSS 的display: none。元素始终在 DOM 里只是看不见。v-if则是真正的条件渲染条件为真时创建元素条件为假时销毁元素。template div v-showisVisiblev-show还在 DOM 里/div div v-ifisVisiblev-if条件为假我就没了/div /template这个区别带来的性能含义是频繁切换的场景用v-show因为只是改样式属性开销小很少切换、初始不一定会渲染的场景用v-if因为可以避免创建永远用不到的 DOM 节点。5.2 v-if 的完整形态v-else-if 和 v-elsev-if不是一个人战斗。它通常和v-else-if、v-else连用形成完整的条件链。这三个指令之间不能插入其他元素否则 Vue 会警告。template div v-ifscore 90优秀/div div v-else-ifscore 60及格/div div v-else不及格/div /template这里要注意的是Vue 的条件链是按顺序判断的写在前面的优先级更高。实际编码时不要用一串v-if并列处理互斥逻辑这会破坏可读性。5.3 v-if 和 v-for 的优先级Vue3 和 Vue2 正好相反这一小节是面试高频考点也是很多老项目里肉眼可见的坑。Vue2 中v-for的优先级高于v-if意思是在同一个元素上v-for会先执行再对每一项执行v-if。Vue3 中反过来了v-if优先于v-for。具体到代码上最典型的坏味道是template div v-foritem in list :keyitem.id v-ifitem.visible{{ item.name }}/div /template在 Vue2 里它会先循环再过滤性能不好但能跑在 Vue3 里它会优先判断v-if而v-for还没执行item根本不存在直接报错。所以我的建议是使用v-if过滤v-for列表时把它改成用一个计算属性computedList先算好最终要渲染的列表然后只用v-for渲染。template div v-foritem in visibleList :keyitem.id{{ item.name }}/div /template script setup import { computed } from vue const visibleList computed(() props.list.filter(item item.visible)) /script6. 列表渲染与双向绑定v-for、v-model 的底层逻辑6.1 v-for 遍历数组和对象时拿到的参数v-for的核心能力是遍历数组或对象并渲染重复结构。数组场景拿三个参数值、索引、整个数组。template ul li v-for(item, index, array) in items :keyindex{{ index }} - {{ item }}/li /ul /template对象场景拿三个参数值、键名、索引。template div v-for(value, key, index) in userInfo :keykey{{ key }}: {{ value }}/div /templatev-for还可以遍历数字范围比如v-forn in 5这会渲染 5 次。开发中不常用但偶尔在写骨架屏时能派上用场。6.2 key 的作用为什么不能用 index 偷懒:key是v-for最重要的搭档。Vue 通过 key 来识别每个节点在更新前后是否属于同一个元素。如果 key 相同Vue 会复用现有 DOM 节点只更新变化的内容如果 key 变了Vue 会销毁旧节点创建新节点。很多人图省事用 index 当 key。表面上看起来没问题但一旦列表顺序发生变化或者有增删操作index 就会错乱。举个例子列表 A B Cindex 分别是 0 1 2删除第二项 B 后新的列表 A Cindex 变成 0 1。原本 key 为 1 的元素从 B 变成了 CVue 会误以为 B 变成了 C导致状态复用错位。如果每个列表项内部有自己的状态比如输入框内容、选中态、展开态这种错位会直接变成线上 bug。老老实实用稳定且唯一的业务 ID 作为 keytemplate div v-foritem in list :keyitem.id{{ item.name }}/div /template6.3 v-model表单控件和数据之间的双向车道v-model是 Vue 最著名、也最容易让新手误解的指令。它做的事可以拆解成两条数据变化时控件显示同步更新用户操作控件时数据同步更新。常见用法template input typetext v-modelname textarea v-modeldescription/textarea input typecheckbox v-modelisChecked select v-modelselectedCity option valueshanghai上海/option option valuebeijing北京/option /select /templatecheckbox 和 select 需要注意绑定值的类型。checkbox 绑定的是布尔值select 绑定的是 option 的 value 属性对应的值。新手常犯的错误是把 checkbox 绑定成字符串然后怎么都不对其实是因为类型不匹配。v-model还有三个常用修饰符.lazy让更新只在change事件时触发而不是每次input.number自动把输入转成数字.trim自动去除首尾空格。看个组合template input typetext v-model.trim.lazyusername input typenumber v-model.numberage /template6.4 v-model 在组件上的用法父子组件间的通信糖v-model不只是表单控件的工具。在组件上使用时v-modelvalue等价于传入:modelValuevalue并监听update:modelValuevalue $event。子组件里想修改 modelValue 时不能直接赋值而是要触发更新事件template input :valuemodelValue input$emit(update:modelValue, $event.target.value) /template script setup defineProps([modelValue]) defineEmits([update:modelValue]) /script从此你就理解了为什么很多人说 v-model 是语法糖。这也是面试中常问的“自定义 v-model 怎么实现”的答案。如果你想更暴力一点Vue3.4 之后还引入了defineModel()这个辅助宏它进一步简化组件的 v-model 绑定这几年新项目里可以直接用。6.5 我在真实项目里对这几个指令的使用频率排序统计一下自己写过的组件指令的使用频率大概是这样v-if和v-for最高几乎每个列表组件都会出现v-model在表单页面大量使用v-on到处都是因为交互离不开事件v-bind在组件传参时使用率极高v-show比v-if少很多主要用在 Tab 切换和弹窗显隐这类高频切换场景v-text几乎不用v-html只有富文本详情页才会碰一下。这个现象背后的逻辑是工程现实列表页和详情页是最常见的业务页面形态表单页是数据录入的主要入口所以对应指令出现频率自然高。你不必每个指令都用到手软关键是形成“看到需求能立刻对应到合适指令”的反射。7. 常见问题与排查技巧实录7.1 v-if 切换后数据没重置这是真实项目里很经典的问题。用v-if切换两个表单区域A 区域里用户填了一些内容切到 B 再切回 A发现刚才填的内容都还在。原因是 Vue 复用了同一个 DOM 节点。解决方案有两种在想要重置的元素上加上:key用不同的 key 让 Vue 认为这是不同的节点从而销毁重建或者在切换时手动清空数据。前者更优雅。我发现如果代码里到处都是“切换前手动重置数据”的写法而且写的人自己也觉得繁琐十有八九是忘了加 key。7.2 v-for 渲染出来的列表点击事件拿不到当前项数据典型的写法错误是template li v-foritem in list clickhandleClick(item){{ item.name }}/li /template这句代码本身没有问题但如果handleClick里对item做了异步操作而item后续被外部修改了引用地址可能拿到的就是过期的数据。这个坑比较隐蔽建议在事件处理函数开头先拷贝一份快照数据再操作比如const current {...item}。还有一种情况是原生 DOM 事件想拿 indextemplate li v-for(item, index) in list :data-indexindex clickhandleClick{{ item.name }}/li /template方法内通过event.target.dataset.index获取 index。这种写法在必须操作原生 DOM 的场景里有奇效。7.3 v-model 绑定到对象属性页面不更新Vue3 使用 Proxy 做响应式代理这类问题比 Vue2 少多了。但在 Vue2 里直接给对象新增一个属性是响应不到的需要$set。如果你还在写 Vue2一定要记住这个差异。Vue3 里虽然可以检测到新增属性但如果你直接把对象替换成新对象而不是修改内部属性也是常见的“页面不更新”原因。这说明你在数据处理上可能没有遵循响应式的心智模型——尽量提前定义完整结构避免运行时动态扩展字段这也能减少很多类型相关的隐性 bug。7.4 快速定位模板渲染问题的步骤如果页面上某一块没渲染出来我的排查顺序是先看控制台有没有警告再用 Vue Devtools 确认组件实例上的数据到底有没有值然后确认指令有没有写错——比如v-if是不是写在v-for之前Vue3 会直接报错最后检查表达式是否有语法错误有时候少写一个闭合字符Vue 的编译器会给出很长的一段英文报错别慌往死里看开头几行就有具体位置。8. 把指令串起来一个综合小例子纸上谈兵这么多最后给一个综合的小例子把前面重点提到的指令揉在一个组件里。这是一个简单的“待办事项”输入和列表组件麻雀虽小但五脏俱全。template div h3待办事项/h3 input typetext v-model.trimnewTodo placeholder输入任务 keyup.enteraddTodo button clickaddTodo添加/button ul li v-fortodo in visibleTodos :keytodo.id :class{ completed: todo.done } input typecheckbox v-modeltodo.done span v-if!todo.editing{{ todo.title }}/span input v-else typetext :valuetodo.title inputtodo.title $event.target.value blurtodo.editing false button clicktodo.editing true编辑/button button clickremoveTodo(todo.id)删除/button /li /ul p v-showvisibleTodos.length 0暂无待办事项/p /div /template script setup import { ref, computed } from vue const newTodo ref() const todos ref([ { id: 1, title: 学习 Vue 指令, done: false, editing: false }, { id: 2, title: 写一篇技术博客, done: true, editing: false } ]) const visibleTodos computed(() todos.value.filter(item !item.done || item.editing)) function addTodo() { const title newTodo.value.trim() if (!title) { return } todos.value.push({ id: Date.now(), title, done: false, editing: false }) newTodo.value } function removeTodo(id) { todos.value todos.value.filter(item item.id ! id) } /script style scoped .completed { text-decoration: line-through; color: #999; } /style这个例子涵盖了v-model的输入与复选框绑定、v-for渲染列表与 key 的使用、v-if/v-else切换编辑与显示状态、v-show控制空状态提示、:class动态绑定完成样式、click/keyup.enter处理交互。算是把前面所有指令用实践串了起来。你可以在脚手架项目里跑一下配合 Vue Devtools 观察数据变化和 DOM 更新的对应关系理解会深很多。我自己的经验是学 Vue 指令不需要也不应该死记硬背。你只需要理解模板和数据之间那些固定的映射规则比如属性和内容怎么绑定、条件怎么分支、列表怎么循环、表单怎么双向同步剩下的就是多写多踩坑。踩过v-show和v-if选错的坑、踩过key用 index 的坑、踩过v-model绑定对象属性不更新的坑之后你对它们的印象会比背十遍文档都深刻。