1. 先搞清楚Windows装Vue2环境你到底需要什么1.1 一套完整的Vue2开发环境由哪些部分组成很多新手第一次在Windows机器上装Vue2环境以为下载一个东西装好就能写代码了结果折腾一下午不是这里报错就是那里挂掉。我先说一个结论Vue2本身不是一个软件它是一个JavaScript框架跑在浏览器里。真正需要安装的是能够运行、构建、调试Vue2项目的那一整套工具链。这套工具链在Windows上主要由四块拼起来Node.js项目运行时的基础。Vue CLI脚手架、npm包管理器、项目打包都依赖它。包管理器npm/yarn/cnpm用来下载第三方依赖包。Vue2项目的组件库、工具库全靠它从远程仓库拉下来。Vue CLI脚手架帮我生成标准化的Vue2项目结构、配置好webpack构建流程、提供开发服务器和热更新。这是省事的关键。代码编辑器 浏览器写代码和看效果的地方。编辑器我推荐VSCode装几个Vue插件后写.vue单文件组件非常舒服。这四块缺一不可。很多人卡住往往不是因为Vue2本身难而是Node版本不对、npm下载太慢、CLI版本选错。后面我会逐个拆开讲你照着操作就不会踩坑。1.2 Vue2项目的三种创建方式选哪种最稳想创建一个Vue2项目从实操层面看市面上流行的方法有三类我全部实测过给大家做个对比创建方式操作命令/入口适用场景稳定程度Vue CLI 4/5 创建vue create 项目名新项目、绝大多数学习者、公司常规项目最稳推荐Webpack模板创建vue init webpack 项目名老项目、课程教学基于该模板可用但依赖陈旧可视化工具/HBuilderX图形界面点选刚入门不熟悉命令行的同学方便但不灵活我的建议是优先用Vue CLI来创建。因为Vue CLI把webpack那一大堆复杂配置都帮你封装好了创建出来的项目既标准又能直接跑。而手工去配webpack虽然能学到原理但对只想用Vue2干活的人来说太耗时间。至于HBuilderX这类工具适合写完即跑的简单演示真到了要上线的项目还是命令行工具更可控。2. Node.js版本选择与安装细节Windows版2.1 为什么Vue2对Node版本有讲究你可能觉得装Node.js还不简单去官网下一个最新的装上就行。但Vue2这个老同志偏偏对Node版本有要求用太新的Node版本编译时会直接翻脸报错。核心原因在于Vue2时代的依赖大多依赖node-sass这类原生模块它们需要针对特定Node版本编译。一旦Node版本太新比如17、18、20node-sass找不到对应的二进制包npm install阶段就会反复报错。另一个高频报错是digital envelope routines::unsupported这是Node 17及以上版本改用了OpenSSL 3.0老项目打包时哈希算法不兼容导致的。所以我的经验是Windows上跑Vue2Node版本落在14.x到16.x最稳妥。特别是Node 14.18.1、16.13.2这些带LTS长期维护标识的版本兼容性最好。如果你电脑里已经装了新版本Node也不急着卸载后面在常见问题部分我会专门讲怎么绕开这个坑。2.2 安装Node.js的关键步骤与配置项解读安装Node.js这一步只要注意几个细节基本不会出问题。去Node.js官网的下载历史区域找到对应你系统位数64位还是32位的Windows Installer (.msi)文件下载14.x或16.x版本即可。双击安装包后一路Next的时候有两点要留神安装目录建议保持默认的C:\Program Files\nodejs\或者换到一个纯英文路径千万别放中文目录。很多开发工具的编译环节一旦路径里出现中文就会莫名其妙地找不到文件。Add to PATH选项一定要勾选。安装器默认会把它选中这样Node和npm命令才能在任意命令行窗口直接使用。安装完成后打开一个新的PowerShell窗口或CMD窗口分别输入这两条命令验证node -v npm -v如果显示出版本号比如v16.13.2和8.1.2说明安装成功。记得一定要重启终端如果是在安装Node之前就开着的老终端窗口它不会自动刷新环境变量。2.3 配置淘宝镜像为什么必须做这一步很多人会忽略但我觉得它是整个环境搭建里性价比最高的一步。npm默认下载依赖走的是官方源https://registry.npmjs.org/服务器在国外国内网络环境下载速度经常是几十KB/s装一个小项目等十几分钟是常有的事。解决办法就是把npm的下载源换成国内的镜像仓库我比较推荐淘宝npm镜像。在命令行里执行npm config set registry https://registry.npmmirror.com然后验证一下是否生效npm config get registry看到输出https://registry.npmmirror.com就说明配置好了。实测在同样网络环境下载vue全家桶换源之后速度能从几十KB/s提升到几MB/s可以说是天壤之别。后面不管装什么依赖这笔投资都会一直受益。3. Vue CLI 的安装与版本坑3.1 全局安装Vue CLI的命令与版本陷阱Node和npm到位后接下来安装Vue CLI脚手架。命令很简单npm install -g vue/cli4-g表示全局安装这样你可以在任意目录下使用vue这个命令。我在这一步强调一下版本陷阱不要直接装最新版vue/cli5.x/6.x就完事虽然它也能创建Vue2项目但内部依赖整体偏新在旧机器和旧Node环境下容易出幺蛾子。考虑到我们目标是Vue2用vue/cli4是最省心的组合它创建Vue2项目时依赖版本匹配度最高。还有一点要区分清楚我们在这里装的vue/cli是Vue CLI的3.x/4.x版本命令是vue create。而早期还有一个叫vue-cli的2.x版本命令是vue init两者是不同的包。如果你之后要接触老模板项目还需要额外安装npm install -g vue-cli后面我会详细说。3.2 验证安装是否成功的正确姿势安装完成后同样在命令行输入vue --version正常情况下会打印类似vue/cli 4.5.19这样的版本号。如果没有输出版本号而是提示无法识别vue命令大概率是npm的全局安装目录没有加到系统PATH环境变量里。如果你用的是msi安装的Node全局目录通常就在C:\Users\你的用户名\AppData\Roaming\npm需要手动把这个路径加进环境变量。另外提醒一句如果你在Windows PowerShell里执行命令时报错提示禁止运行脚本这是因为PowerShell默认的脚本执行策略限制。可以以管理员身份运行一次Set-ExecutionPolicy -Scope CurrentUser RemoteSigned输入Y确认即可。Vue CLI安装本身不需要这条命令但你之后跑npm的某些脚本时可能会用到提前设好省得临时抓瞎。4. 创建Vue2项目的两种主路径4.1 用Vue CLI 4/5 快速创建Vue2项目环境工具都备齐后就可以正式创建项目了。我先说最推荐的vue create方式。打开命令行cd到你希望存放项目的目录然后执行vue create my-vue2-project这里my-vue2-project就是项目名注意项目名只能是小写字母、数字和连字符不能有大写字母和中文这是npm包名的硬性规则。回车后会出现交互式选项我带你走一遍最关键的几步第一步会问Please pick a preset意思是选择预设配置。如果你是第一次用选Manually select features手动选择功能。第二步进入功能选择列表方向键上下移动空格键选中/取消。对Vue2项目我建议至少勾上Babel、Router、Vuex如果要用CSS预处理器再勾上CSS Pre-processors。ESLint可以根据个人习惯想严谨一点就选上不想被代码风格烦扰可以先不勾。第三步问Choose a version of Vue.js这里一定要选2.x。第四步问Use history mode for router?是问路由是否用history模式。新手建议选n用hash模式部署到任意服务器都不需要额外配置。后续还会问一些小的选项比如在哪放配置文件、是否保存预设直接回车选默认就行。等进度条跑完你的项目就创建出来了目录里就是一套标准的Vue2单页应用骨架。4.2 用旧版Webpack模板创建项目如果你在公司维护的是老项目或者某些课程还在用vue init webpack这套流程就需要额外装一个2.x版的脚手架包npm install -g vue-cli装好后创建项目的命令是vue init webpack my-vue2-project这种方式同样是交互式引导会让你填项目名称、描述、作者还会问你Runtime Compiler还是Runtime-only选默认的Runtime Compiler即可。还要回答是否安装vue-router、是否启用ESLint、是否安装单元测试端到端测试框架这些根据你的实际需求选拿不准就全选no先跑起来最重要。这里有一个老手才知道的坑用vue init创建的项目依赖非常老lock文件里的包版本是好几年前的了npm install时很容易和现在的Node版本冲突。如果装完依赖启动报错优先尝试在项目跟目录手动升级一下webpack-dev-server的相关版本或者直接用Vue CLI 4创建项目后手动补webserver配置。4.3 项目目录结构逐个拆解不管用哪种方式创建Vue CLI 4创建出来的项目和Webpack模板的目录非常接近核心内容都集中在src目录下。我给大家逐个说明方便你创建完项目后不迷路my-vue2-project/ ├── node_modules/ # 所有依赖包都在这里不用管 ├── public/ │ └── index.html # 唯一的HTML入口Vue挂载点在这 ├── src/ │ ├── assets/ # 静态资源图片、CSS、字体等 │ ├── components/ # 公共组件比如某个按钮、某个弹窗 │ ├── router/ # 路由配置文件 │ ├── store/ # Vuex状态管理配置 │ ├── views/ # 页面级组件 │ ├── App.vue # 根组件所有页面的容器 │ └── main.js # 入口文件创建Vue实例的地方 ├── package.json # 项目依赖和脚本配置 ├── vue.config.js # Vue CLI配置文件可以手动创建 └── babel.config.js # Babel转译配置里面最重要的两个文件是main.js和App.vue。main.js干的事就是创建Vue实例、挂载路由、引入Vuex然后把App.vue渲染进public/index.html里那个idapp的div。App.vue则是整个组件树的根节点里面用router-view/占位路由匹配到哪个页面就渲染到哪个位置。弄清这套结构后你再去看Vue2的组件通信、路由跳转、状态管理就有了坐标感。5. 项目启动、依赖安装与常见报错5.1 npm install 卡住或太慢的解决方案项目创建好之后第一件事是安装依赖。如果创建项目时Vue CLI已经帮你装好了node_modules这一步可以跳过如果是手动拉下来的老项目或者创建时选择了不自动安装那就要手动执行npm install只要前面你配好了淘宝镜像这一步通常很顺畅。如果你确实遇到卡住的情况我建议按这个顺序排查按Ctrl C中断当前安装然后执行npm cache clean --force清掉缓存再重新npm install。检查配置的registry是否生效执行npm config get registry确认为https://registry.npmmirror.com。如果还是极慢可以考虑用cnpm这类替代客户端。执行npm install -g cnpm --registryhttps://registry.npmmirror.com之后用cnpm install代替npm install。但我要提醒一句cnpm安装的依赖是扁平的有时候会把包结构弄乱导致某些需要精确版本依赖的库运行异常。所以我的习惯是只用npm淘宝镜像不用cnpm除非npm确实装不上。5.2 npm run serve 启动与热更新依赖装完在项目根目录执行npm run serveVue CLI会编译项目并启动一个本地开发服务器默认地址是http://localhost:8080/。看到控制台输出Compiled successfully后浏览器打开这个地址就能看到Vue2的欢迎页面。这一步最爽的就是热更新。你保存src下的任何文件浏览器页面会自动刷新或者局部更新不需要手动刷新更不需要重新启动服务。这个能力是webpack-dev-server提供的Vue CLI把它封装好了。热更新的原理简单说就是开发服务器监听文件变化通过WebSocket把更新推送给浏览器浏览器拿到新的模块后无缝替换。如果8080端口被别的程序占用了命令行会提示你是否换一个端口输入Y确认即可自动跳到8081。想固定某个端口的话可以在项目根目录创建vue.config.jsmodule.exports { devServer: { port: 3000, host: localhost, open: true } };open: true表示启动后自动打开浏览器host设置成localhost可以避免本机访问时偶发的主机解析问题。5.3 高频报错与排查速查表我见过太多人卡在同样的报错上下面把最高频的几个拿出来复盘。这份速查表你能收好碰到问题直接对号入座。报错信息出现原因解决方案digital envelope routines::unsupportedNode版本是17老项目用OpenSSL 3.0临时方案NODE_OPTIONS--openssl-legacy-provider npm run serveModule build failed: Error: Node Sass does not yet support your current environmentnode-sass与Node版本不匹配卸载重装npm uninstall node-sass然后npm install sass1.26.5或改用dart-sassError: Cannot find module node-sass依赖没装全或安装中断执行npm install重新安装确认镜像源可用Port 8080 is already in use8080端口被占用命令行提示时输入Y换端口或者修改vue.config.js指定其他端口npm ERR! code EINTEGRITY下载的包完整性校验失败rm -rf package-lock.json node_modules后重新npm installFailed to compile with errors: ESLint ...代码风格不符合ESLint规则按提示修改文件或关闭ESLint检查在vue.config.js里把lintOnSave设为falsenetwork: unavailable开发环境网络状态没就绪常见于改用本地地址访问检查vue.config.js的host配置改回localhost或直接把devServer配置删掉这里额外说两个非常规的报错因为它们也出现在我近期处理Vue2项目的高频话题里。第一个是浏览器控制台弹出的permissions policy violation: unload is not allowed in this document.。这个不是项目代码的致命错误而是新版浏览器对页面卸载事件权限策略更严格了vue-router或某些插件在页面关闭时注册过beforeunload监听被浏览器拦下来了。处理方式是在路由组件的beforeDestroy钩子里手动移除事件监听或者忽略它不影响功能。第二个是关于Vue3迁移的问题你可能会搜到很多vue2转vue3的帖子。这里明确一个认知Vue2和Vue3在API上差异不小组合式API、响应式原理、自定义指令语法、全局API挂载方式全都不一样。如果你当前的目标是跑通Vue2项目就先安心把写法固定在Vue2的选项式API上看看Vue2生命周期beforeCreate、created、mounted、beforeDestroy这些和组件通信不要混着看Vue3的教程容易混乱。最后再分享一个我个人的使用习惯。在Windows上装环境这件事本质上就是给编译工具之间精确配合创造条件。我不想折腾的时候会固定使用Node 16.13.2 vue/cli 4.5.19这套组合装任何Vue2项目。这不是什么秘密而是经历过足够多的报错和回滚后沉淀下来的最省心的搭配。你们也可以按照自己机器的实际情况微调但只要认准Node版本别太新、Vue CLI用4.x、镜像源一定换、项目名别用中文这四条军规Vue2环境在Windows上基本不会把你拦在门外。