一次vue-cli4项目升级到vite的经历
发布网友
发布时间：2024-09-17 02:28
共1个回答
热心网友
时间：2024-09-17 20:55
使用vue-cli4的项目，业务写多了之后开发运行和打包都慢了很多，为了提升开发体验以及更新团队技术框架，需要升级到更高级的脚手架上，两种方案：一是升级到vue-cli5，二是升级到最新的vite。
其中第一种方案升级简单，经过实验，打包的速度不升反慢，这可能和项目中的有依赖以及业务代码有关。
第二种方案升级vite，经过可行性调查，升级到vite的成功率非常高，最后决定从vue-cli4升级到vite，这是一个高风险高回报的事情，因为尽管市面上已存在很多升级成功的案列，但是每个项目都不一样，我们的项目也很庞大，依赖很多，并没有100%升级成功的把握。而升级成功的回报也很显而易见，开发环境几乎秒运行，开发体验得到了显著提升。
升级前后对比||vue-cli4|vite||---|---|---||开发启动时间|33306ms|1247ms||生产打包时间|78s|81s||打包体积|42.6MB|28.6MB||运行期间同一代码改动编译时间|1427ms|瞬时|
生产环境打包时间可能和我们项目中用到了太多vite插件有关系，但开发环境的提升非常显著。
项目状况项目中用到的Vue2，VueCli版本：4.5.13，版本更新时间为2021.5.8，vueCli4的最后版本为4.5.17(2022.3.23)，依赖的webpack版本为^4.0.0
组件库使用vant，依赖Less预处理器，通过vue.config.js配置设置了less主题色，在webpack仅支持less-loader@5版本以及对应的less版本
业务css预处理器为stylus:"^0.54.5"，对应stylus-loader:"^3.0.2"
进行了多页打包（MPA）
使用了workbox-webpack-plugin插件配置了PWA：WorkboxWebpackPlugin
配置了多个路径映射（alias别名）
指定了文件输出路径以及hash配置
生产环境下关闭productionSourceMap以及css的sourceMap提升打包速度
proxy开启多个代理
用到了.env文件中的环境变量
按照开发规范忽略部分文件后缀以及index.js
移除了preload脚本
期望结果可以使用vite进行开发和打包
仍保留webpack打包功能（因为项目太大，不能保证升级到vite后会不会有问题，所以仍希望webpack原本功能正常运行）
准备工作升级Node版本，vite只支持node12及以上，建议升级到v16以上。
安装pnpm工具，pnpm作为更好的npm依赖管理工具，是目前npm和yarn的最好替代品，且有些依赖包使用npm安装时会有异常，使用pnpm安装可解决：pnpm
小项目尝试一键转换升级：wp2vite、webpack-to-vite，这两个工具都提供了一键将webpack项目转成vite的能力，但对于大中型项目，并不可靠。
开始行动1.安装必要依赖pnpm?add?vite-plugin-env-compatible?vite-plugin-html?vite?vite-plugin-vue2?--devvite-plugin-vue2是处理vue2版本代码的插件，如果项目中是vue3，安装的依赖有所不同，请参考webpack-to-vite
2.复制html到根目录，并修改??注意是复制，并只改动复制后的html，这样才不会破坏原有webpack功能。
修改复制后的html，增加对应的js文件引用，注意type属性不能少！
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>多页打包(MPA)，其他页面的html同样操作，不同html引入对应的js即可。
3.新增vite.config.js文件，开始迁移最重要的配置部分空配置如下：
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})4.修改环境变量环境变量主要面临两个问题：
要兼容webpack和vite的环境变量用法
解决方法：使用vite插件vite-plugin-env-compatible，让vite中可以使用webpack中读取环境变量的方式，再配合envPrefix配置，让vite可以读取到VUE_APP_开头的环境变量：
?pnpm?add?vite-plugin-env-compatible?-D?import?{?defineConfig?}?from?'vite'?import?envCompatible?from?'vite-plugin-env-compatible'?export?default?defineConfig({???plugins:?[?????envCompatible()???],???envPrefix:?['VUE_APP_']?//?很重要?})?//?mian.js测试?console.log(process.env.VUE_APP_UNION_STATS)?console.log(import.meta.env.VUE_APP_UNION_STATS)两个打印都得到了正确的结果，注意：vite中默认只能读取到VITE_开头的环境变量，如果不配置envPrefix，则会导致第二个打印为undefind。
vite.config.js中不能读取到环境变量
vite.config.js是无法直接通过import.meta.env和process.env获取环境变量的，我们需要通过vite的loadEnv获取。
我们需要将vite.config.js的导出对象改为函数：
?import?{?defineConfig,loadEnv?}?from?'vite'?export?default?({?mode?})?=>?{?????const?isPro?=?mode?===?'production'?//?我们可以通过mode直接判断当前是不是生产环境，注意mode可以在运行指令中指定：`vite?build?--mode?master`，如果没有指定，那默认打包就是production?????function?getEnv(key)?{?//?定义获取环境变量的方法?????????return?loadEnv(mode,?process.cwd(),'')[key]?//?第三个参数非常重要，下面有详解?????}?????return?defineConfig({?????????base:?getEnv('VUE_APP_PUBLICPATH'),?//?读取环境变量?????????//?...忽略其他代码?????})?})loadEnv有三个参数，前两个参数基本固定不变，而第三个参数默认情况下是不需要传的，只有在配置了envPrefix项，读取非VITE_开头的变量时才需要，在loadEnv源码中我们可以看到，第三个参数是prefixes:string|string[]='VITE_'，也就是环境变量的前缀，默认是VITE_。
如果你的项目和我一样，读取了VUE_APP_PUBLICPATH这样非VITE_开头环境变量，就在loadEnv的第三个参数传递空字符串即可，这样就能读取到所有的环境变量了。
5.兼容commonjs代码项目中有用到commonjs规范的依赖，比如letmd5=require('js-md5').create()，webpack是基于node开发的，支持require语法，在打包的时候webpack也会正确处理这部分代码，但在vite中不会，所以需要将这部分代码改成importmd5from'js-md5'
项目开发环境下，一些node_modules中的包也会存在commonjs的代码，我们可以通过vite的插件?vite-plugin-commonjs来实现这部分代码的转化，保证开发环境的正常运行。
pnpm?add?@originjs/vite-plugin-commonjs?--dev//?vite.config.js??忽略其他代码import?{?viteCommonjs?}?from?'@originjs/vite-plugin-commonjs'export?default?({?mode?})?=>?{????return?defineConfig({????????plugins:?[????????????//?...????????????viteCommonjs()?//?兼容vite中的cjs导入语法????????]????})})6.解决css预处理的问题vite内置了对主流css预处理器的支持（sass/less/stylus），项目使用预处理器时，只需要安装对应预处理依赖即可：
#?.scss?and?.sasspnpm?add?sass?-D#?.lesspnpm?add?stylus?-D#?.styl?and?.styluspnpm?add?stylus?-D比较巧的是，我们项目中用到的Stylus的@import别名的语法和vite冲突，@import'~@/public/stylus/mixins'这样的代码是会报错，一开始我找到了插件，可以帮助我们解决这个问题：vite-plugin-stylus-alias，但是都后面打包的时候发现这个插件有副作用，后面采取了其他方法解决。
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>0<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>1使用这个插件会导致无法生成sourcemap文件，在打包的时候可以看到警告：Sourcemapislikelytobeincorrect:aplugin(vite-plugin-stylus-alias)wasusedtotransformfiles,butdidn'tgenerateasourcemapforthetransformation.Consulttheplugindocumentationforhelp，鉴于插件作者已经很久没有更新，建议能改成相对路径还是直接改，如果引用地方较多，可以定义文件为全局styl文件最新解决方案：一般出现这个报错是因为插件使用了vite的transformapi转换代码，但是return值缺失导致，解决方法：复制插件代码到项目中，在插件transform函数return的结果中，返回map:null，然后再vite.config.js中引用项目中修改后的插件，即可完美解决，如下：文末解决bug有细说
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>2定义stylus全局文件
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>3这里需要注意，官方文档中css-preprocessoroptions写的是使用文件名拓展名作为key，stylus的文件拓展名是styl，但是我使用了stylus作为key并不会有问题，相反使用styl作为key则不生效了，后续这个地方可以留意一下。
在vite源码中，stylus和styl都进行了判断，理论上都可以使用，但目前测试的结果就是styl作为key不生效，可能源码中其他地方还能找到原因。
7.组件库按需导入和定制主题我们项目中用到的组件库是Vant2，该组件库依赖Less，以及通过配置文件来定制组件的主题，在配置中我们需要进行修改：
vue-cli中的主题配置部分如下：
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>4vite中主题配置部分如下：
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>5按需导入项目中按需导入vant组件库，组件可以成功导入，但是组件的样式缺失了，这是因为在webpack中，babel-plugin-import插件帮我们实现了组件的样式导入，在vite中使用?vite-plugin-style-import插件帮我们实现这个功能，不仅vant组件库，其他诸如element、antv等组件库也可以使用这个插件进行按需导入：
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>6<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>78.修改alias别名配置，以及忽略文件后缀vite配置别名的方法和vue-cli有所不同，且没有默认的别名，都需要通过配置实现，且vite默认不能忽略文件后缀导入，我们也需要通过修改配置来实现：
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>8需要注意extensions配置的顺序，从左到右进行匹配，如果存在同名但类型不同的文件，很可能得到期望外的结果，比如同目录下存在index.js和index.vue，按上面的顺序，import'./index?会优先匹配到index.js文件。这种情况建议补全后缀进行导入。
9.配置前端跨域vite配置跨域和webpack也有出入，需要修改配置
<!--?忽略一些代码?--><body>????<div?id="app"></div>????++?<script?type="module"?src="/src/main.js"></script>?++</body>9以上就是几种常见的跨域配置方式，webpack中的devServer改为了server,webpack的proxy中的pathRewrite改成了rewrite，并且类型成为了函数，在函数中返回请求的路径即可。
10.多页打包以及打包的其他配置vite在build.rollupOptions配置多页打包，参考rollupOptions，其他配置参考文档
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})011.配置运行路径base是指项目运行在服务器的哪个路径下，一般通过从环境变量中动态获取。
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})112.配置EsLintvite中使用vite-plugin-eslint插件实现eslint的检查功能，安装过程中发现vite-plugin-eslint@1.4.0会报错，安装1.3.0版本即可。
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})2import?{?defineConfig?}?from?'vite'export?default?defineConfig({})313.使用插件@vitejs/plugin-legacy兼容低版本浏览器plugin-legacy文档
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})414.配置运行指令import?{?defineConfig?}?from?'vite'export?default?defineConfig({})5可以在指令中声明mode环境，这个mode在vite.config.js中可以得到，具体可以参考前面4.修改环境变量
保存运行指令npmrunserve开发环境已经可以跑起来了，但是vite的特性是你用到的页面才会进行打包，其他页面没有进行访问，是不会打包的，所以需要进行打包才能知道其他地方改造会不会有问题，打包如果有报错，再解决报错即可。
14.解决报错globalisnotdefined
这个错误是在node_modules/buffer/index.js?v=43e083a7文件中抛出的，我查看了yarn.lock文件，依赖路径为多个vue-cli插件>webpack@4.0.0>node-libs-browser?>buffer
这个是依赖的问题，第一删除node_modules重新安装依赖。第二更换npm工具为pnpm重装依赖，如果仍不行，建议不建议webpack，删除掉webpack相关依赖。
网上还有一种做法是：在window对象上挂载global对象，可作为备选方案。
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})6@import'~@vant/icons/src/encode-woff2.less';报错
这个错误是vant组件库中的icon组件抛出的，vite默认不能使用别名，我们在前面配置了别名，但是配置的是~@指向项目中的src目录，这样vant组件库的这个文件引用就找不到了。
issuesvant
解决方法：针对vant的这个文件，做一个别名，放到第一位，优先进行匹配：
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})7运行vitebuild，css产生了一些警告。
警告分为两种，一是css中的属性拼写错误，诸如：color写成了colo，background写成了backgrounc，属于语法错误，根据警告提示搜索对应样式进行修改即可。
二是一些语法正确，但还不清楚为什么压缩时提示了警告：比如stylus修改scoped样式用的>>>语法，以及background?rgba(0,0,0,0.5)提示Unexpected"rgba("。
Thepackagemayhaveincorrectmain/module/exportsspecifiedinitspackage.json
这个错误是通过npminstall后运行vite指令报错的，用yarn安装一直很正常，原因是node_modules的某个包的package.json定义的main入口路径错了，所以找不到模块导入。
解决方法：针对这个模块，定义别名，指向正确的入口：
import?{?defineConfig?}?from?'vite'export?default?defineConfig({})8打包后导入函数定义别名后，调用函数报错
import*asminByfrom'lodash.minby'代码报错了，而且只有在生产环境下才产生。
解决方法：暂时去掉别名，这应该和lodash的导出方式modules.export在vite中转化成ES语法的过程有关系。
importminByfrom'lodash.minby'
requireisnotdefine，通过require导入图片资源报错
前面在步骤5已经用了插件vite-plugin-commonjs转化common.js的代码了，require理应不会报错。
但是require导入资源图片算是webpack的功能，和js代码不一样，所以导入资源图片的代码都要进行修改：
require('./images/logo.png')改成importlogofrom'./images/logo.png'
这样的修改可以兼容webpack和vite，这是在现有项目中，改动的地方会达到上百处，非常麻烦。
