简介这是一份面向前端初学者的 Vue 2.0 入门实践小项目聚焦核心概念落地帮助开发者快速掌握 MVVM 框架的基本开发范式。资源包含 54 个文件涵盖 14 个 JavaScript 逻辑文件、5 个 Vue 单文件组件如 TodoList、UserCard 等典型示例、13 张 PNG 界面素材及 4 个 source map 调试文件辅以 README.md 使用说明、.babelrc 编译配置和基础 HTML 入口结构完整、开箱即用压缩包仅 537KB轻量易部署。已有 2143 人学习下载适合零基础或刚接触 Vue 的开发者边跑边学。读者可直接运行项目直观理解双向绑定v-model、列表渲染v-for、条件控制v-if/v-show、组件通信与自定义指令等关键机制并通过源码目录清晰把握 Vue 2.x 工程组织方式与典型开发流程。1. 这不是 Vue 2 的“怀旧纪念品”而是一份能跑通、能调试、能改出业务逻辑的最小可执行现场你手头刚接到一个维护需求某老系统前端用的是 Vue 2后端接口没变但 UI 要加个搜索框分页表格还要支持导出 Excel。你打开官方文档翻到 Vue 2.x 版本页发现vue-cli2已归档、webpack3插件链断裂、vue-router3的懒加载写法和现在主流项目对不上——这时候一份结构干净、无多余依赖、所有npm run dev命令能直接起服务、控制台不报Unknown custom element或Cannot read property xxx of undefined的 Vue 2 小 demo比十篇“Vue 2 生命周期详解”都管用。它不教你怎么写 Composition API也不塞 Vuex 模块化样板它就干三件事挂载根实例、渲染一个带响应式数据的组件、发起一次真实 HTTP 请求并展示结果。适合正在修 Legacy 系统的前端、需要快速验证某个 Vue 2 特性比如v-model在自定义组件上的.sync行为、或带新人做 Vue 2 入门实操的带教者。这不是教学模板是能立刻进 debugger、打 console、改 data、看 re-render 的黑匣子解剖台。2. 从零还原为什么这个 demo 只用vue2.6.14vue-router3.5.3axios0.21.42.1 选型依据避开 Vue 2 生态里最常翻车的三个时间点Vue 2 的生命周期在2.5.x到2.6.x之间有过一次关键收敛beforeDestroy替代beforeDestroy拼写修正$nextTick的 Promise 化在2.6.0后稳定。我们锁定vue2.6.14Vue 2 最终稳定版不是因为它最新而是因为它是最后一个被大量线上项目验证过、且与vue-router3.5.3支持scrollBehavior函数返回对象、vuex3.6.2兼容mapState数组写法完全对齐的版本。axios0.21.4是最后一个支持 IE11 的大版本0.22.0移除了Promisepolyfill 兼容逻辑如果你的 Legacy 系统还要跑在 IE 上跳过这个版本会直接导致axios.get()报undefined is not a function。这些不是玄学是某次凌晨三点线上白屏后A同学翻了三天 commit log 和 npm dist-tags 才确认的血泪经验。2.2 目录结构拒绝vue-cli2自动生成的“迷宫式嵌套”src/ ├── main.js # new Vue({ el: #app, render: h h(App) }) ├── App.vue # router-view/ 全局样式重置 ├── router/index.js # mode: hash, routes: [{ path: /, component: Home }] ├── components/ │ ├── SearchBox.vue # v-model keyup.enter 绑定搜索 │ └── DataTable.vue # props: { list: Array }, slot 分页器 ├── api/ │ └── request.js # axios.create({ baseURL: /api }) └── utils/ └── exportExcel.js # 使用 SheetJS (xlsx) 导出非后端生成注意没有store/目录。这个 demo 不预设状态管理复杂度——90% 的 Vue 2 维护场景data()里的响应式对象 computed足够撑住三个月迭代。强行上 Vuex只会让mapState映射错模块、committype 字符串拼错、dispatch异步 action 里忘记return Promise最后 debug 时在devtools里看到一堆灰色不可编辑的 state怀疑人生。我们把状态留在组件内等真出现跨组件共享、多处修改同一份数据时再拆 Vuex 模块——这是成本可控的演进路径不是教条。2.3main.js关键配置为什么不用new VueRouter()而是createRouter()// src/main.js import Vue from vue import App from ./App.vue import { createRouter } from ./router // 注意不是 import Router from vue-router Vue.config.productionTip false // 创建 router 实例非 new Router() const router createRouter() new Vue({ router, // 注入 router render: h h(App) }).$mount(#app)提示Vue 2 中vue-router3并不提供createRouter()工厂函数——这是本 demo 的自定义封装。目的是把路由实例创建逻辑抽离方便后续注入 mock 数据或添加全局前置守卫。实际./router/index.js内部仍是new Router({})但对外隐藏了构造细节。这种写法让main.js更像一个“装配线”而不是“胶水代码”。createRouter()内部实现// src/router/index.js import Vue from vue import Router from vue-router Vue.use(Router) export function createRouter() { return new Router({ mode: hash, // 避免后端 404开发期零配置 routes: [ { path: /, name: Home, component: () import(/components/Home.vue) // 路由懒加载但不用 webpackChunkName 注释 } ], scrollBehavior(to, from, savedPosition) { // hash 模式下返回上一页时滚动到原位置 if (savedPosition) return savedPosition if (to.hash) return { selector: to.hash } return { x: 0, y: 0 } } }) }参数说明mode: hash不依赖后端配置http://localhost:8080/#/user可直接刷新避免history模式下 404scrollBehavior解决单页应用中页面跳转后滚动条卡在顶部的问题savedPosition是浏览器原生history.state保存的位置component: () import(...)启用 webpack 代码分割但不加/* webpackChunkName: home */—— 因为小 demo 无需 chunk 命名管理加了反而增加构建复杂度。3. 核心功能落地SearchBox DataTable 的响应式联动与防抖实践3.1 SearchBox.vuev-model 的双向绑定本质与事件穿透控制!-- src/components/SearchBox.vue -- template div classsearch-box input refinput v-modellocalQuery keyup.enterhandleSearch blurhandleBlur placeholder输入关键词搜索... classsearch-input / button clickhandleSearch classsearch-btn搜索/button /div /template script export default { name: SearchBox, props: { value: String // 支持 .sync 语法v-modelquery 等价于 :valuequery inputval query val }, data() { return { localQuery: this.value || // 初始化时读取父组件传入的 value } }, watch: { // 当父组件修改 value 时同步更新本地值.sync 的核心 value(newVal) { this.localQuery newVal }, // 当本地值变化时通知父组件触发 input 事件 localQuery(newVal) { this.$emit(input, newVal) } }, methods: { handleSearch() { this.$emit(search, this.localQuery) }, handleBlur() { // 失焦时 trim 空格避免空格搜索 const trimmed this.localQuery.trim() if (trimmed ! this.localQuery) { this.localQuery trimmed this.$emit(input, trimmed) } } } } /script逻辑说明v-model在自定义组件中本质是:value input的语法糖必须显式声明props: { value }并$emit(input, ...)watch双向同步父 → 子value变更和子 → 父localQuery变更缺一不可否则.sync失效blur中trim()是真实业务高频坑用户粘贴带空格的 ID后端查不到排查半天发现是前端没清理。3.2 DataTable.vue如何用v-for安全渲染列表并避免 key 重复!-- src/components/DataTable.vue -- template div classdata-table table classtable thead tr th v-forcol in columns :keycol.key{{ col.label }}/th /tr /thead tbody tr v-for(row, index) in list :keygetRowKey(row, index) td v-forcol in columns :keycol.key {{ getCellData(row, col) }} /td /tr /tbody /table div classpagination v-ifpagination button clickprevPage :disabledcurrentPage 1上一页/button span第 {{ currentPage }} 页 / 共 {{ totalPages }} 页/span button clicknextPage :disabledcurrentPage totalPages下一页/button /div /div /template script export default { name: DataTable, props: { list: { type: Array, default: () [] }, columns: { type: Array, default: () [] }, pagination: { type: Object, default: () null } }, data() { return { currentPage: 1, pageSize: 10 } }, computed: { totalPages() { return Math.ceil(this.list.length / this.pageSize) } }, methods: { getRowKey(row, index) { // 优先用 row.idfallback 到 index仅开发期兜底生产环境必须有唯一 id return row.id ! null ? row.id : row-${index} }, getCellData(row, col) { // 支持嵌套属性col.key user.name → row.user.name return col.key.split(.).reduce((obj, key) obj?.[key], row) ?? }, prevPage() { if (this.currentPage 1) { this.currentPage-- this.$emit(page-change, this.currentPage) } }, nextPage() { if (this.currentPage this.totalPages) { this.currentPage this.$emit(page-change, this.currentPage) } } } } /script参数说明getRowKey()v-for的:key必须是稳定、唯一、可预测的值。index是最差选择列表增删时 key 错位导致 DOM 复用异常所以优先取row.idgetCellData()支持user.profile.avatar这类嵌套路径用?.链式安全访问避免Cannot read property profile of undefinedpaginationprop 是对象而非布尔值包含total,pageSize,currentPage时才显示分页栏否则只渲染表格——保持组件职责单一。3.3 防抖搜索为什么不能只靠lodash.debounce// src/components/SearchBox.vue import { debounce } from lodash export default { // ...其他代码 data() { return { localQuery: this.value || , // 防抖函数需绑定 this否则在定时器中 this 指向丢失 debouncedSearch: debounce(function(query) { this.$emit(search, query) }, 300) } }, methods: { handleSearch() { // 触发防抖函数 this.debouncedSearch(this.localQuery) } }, beforeDestroy() { // 组件销毁前清除防抖定时器防止内存泄漏 this.debouncedSearch.cancel() } }注意debounce返回的函数必须在data()中初始化并在beforeDestroy中调用.cancel()。若在methods中每次调用都新建debounce(...)会导致多个定时器共存搜索框失焦后仍可能触发已废弃的请求。4. 避坑指南Vue 2 小 demo 中 5 个高频“秒级崩溃”现场4.1 现象页面空白控制台报TypeError: Cannot read property install of undefined原因在main.js中写了Vue.use(VueRouter)但import VueRouter from vue-router时路径错误如写成vue-router/dist/vue-router.min.js导致VueRouter是undefined。解决检查node_modules/vue-router/package.json的main字段Vue 2 应使用dist/vue-router.common.jsCJS或直接import Router from vue-router让 webpack 自动解析。4.2 现象v-model在自定义组件中失效输入无反应原因父组件用了v-modelquery但子组件未声明props: { value }或未$emit(input, newVal)或watch中漏掉value→localValue的同步。解决用console.log打印this.$props和this.$listeners确认input事件监听器是否存在检查子组件props是否拼写为value不是val或modelValue。4.3 现象axios请求返回 404但后端接口明明存在原因axios.create({ baseURL: /api })中baseURL以/开头导致请求地址为http://localhost:8080/api/users而开发服务器代理规则匹配的是/api/**注意双星号。若代理配置漏掉**则/api/users不会被转发。解决检查config/index.jsvue-cli2或vue.config.js中devServer.proxy配置确保为{ /api: { target: http://localhost:3000, changeOrigin: true, pathRewrite: { ^/api: } } }且pathRewrite正确移除前缀。4.4 现象router-link点击无反应URL 变化但视图不更新原因router/index.js中routes数组里某个component路径写错如import(/views/User.vue)但文件实际叫UserView.vuewebpack 不报错但component值为undefinedVue 渲染空节点。解决在router.beforeEach中加console.log(to)确认to.matched是否为空数组用require.context动态检查组件路径是否存在开发期脚本。4.5 现象IE11 下白屏控制台报Object.assign is not a function原因vue2.6.14默认不包含Object.assignpolyfill而某些插件如xlsx内部使用了该 API。解决在main.js顶部添加import core-js/stable/object/assign或使用babel-polyfill需babel/preset-env配置{ useBuiltIns: usage }。5. 进阶技巧用vm.$forceUpdate()破解响应式失效以及何时该用它5.1 响应式失效的典型场景直接赋值新增属性Vue 2 的响应式系统基于Object.defineProperty它无法检测对象属性的动态添加。例如// ❌ 错误新增属性不会触发视图更新 this.user.newField value // user 是 data 中定义的对象 // ✅ 正确使用 $set this.$set(this.user, newField, value) // ✅ 或替换整个对象触发重新观测 this.user { ...this.user, newField: value }但有些场景$set不好用比如第三方库如 ECharts、Mapbox返回的实例对象你无法控制其属性赋值方式或者data中定义的是null之后被赋值为普通对象但该对象内部属性后续又动态增加。这时$forceUpdate()就成了后悔药——它强制当前组件重新执行render函数绕过响应式依赖收集直接刷新 DOM。5.2 实战案例ECharts 图表数据更新后不重绘!-- src/components/Chart.vue -- template div refchartContainer classchart/div /template script import * as echarts from echarts export default { name: Chart, props: { options: Object // e.g. { title: {}, series: [] } }, data() { return { chart: null } }, mounted() { this.initChart() }, beforeDestroy() { if (this.chart) this.chart.dispose() }, watch: { options: { handler(newOpts) { // ECharts 的 setOption 是异步的但有时 deep watch 仍不触发重绘 if (this.chart newOpts) { this.chart.setOption(newOpts, true) // 第二个参数 true 表示不合并全量替换 // 如果图表仍不更新强制刷新组件 this.$forceUpdate() } }, deep: true, immediate: true } }, methods: { initChart() { this.chart echarts.init(this.$refs.chartContainer) // 初始渲染 if (this.options) { this.chart.setOption(this.options) } } } } /script注意$forceUpdate()是最后手段。优先检查是否遗漏deep: true、immediate: true或setOption是否传了错误参数。滥用forceUpdate会导致性能下降因为它跳过了 Vue 的依赖追踪优化。5.3 一个更隐蔽的坑v-for中:key用Math.random()曾有个同事为“保证 key 唯一”在v-for中写:keyMath.random()。结果每次list更新所有key都变Vue 强制销毁重建所有 DOM 节点滚动位置丢失、输入框失焦、动画中断。后来他改成:keyitem.id || index问题消失。从那以后我每次写v-for都强制走一遍console.log(item.id)—— 如果id是undefined立刻补后端字段或加默认值绝不碰random()。希望帮到你。本文还有配套的精品资源点击获取