背景
使用vue-cli4的项目，业务写多了之后开发运行和打包都慢了很多，为了提升开发体验以及更新团队技术框架，需要升级到更高级的脚手架上，两种方案：一是升级到vue-cli5，二是升级到最新的vite。
其中第一种方案升级简单，经过实验，打包的速度不升反慢，这可能和项目中的有依赖以及业务代码有关。
第二种方案升级vite，经过可行性调查，升级到vite的成功率非常高，最后决定从vue-cli4升级到vite，这是一个高风险高回报的事情，因为尽管市面上已存在很多升级成功的案列，但是每个项目都不一样，我们的项目也很庞大，依赖很多，并没有100%升级成功的把握。而升级成功的回报也很显而易见，开发环境几乎秒运行，开发体验得到了显著提升。
升级前后对比
| vue-cli4 | vite | |
|---|---|---|
| 开发启动时间 | 33306ms | 1247ms |
| 生产打包时间 | 78s | 81s |
| 打包体积 | 42.6 MB | 28.6MB |
| 运行期间同一代码改动编译时间 | 1427ms | 瞬时 |
生产环境打包时间可能和我们项目中用到了太多vite插件有关系，但开发环境的提升非常显著。
项目状况
- 项目中用到的Vue2，Vue Cli版本：
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 -Dimport { 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规范的依赖，比如let md5 = require('js-md5').create()，webpack是基于node开发的，支持require语法，在打包的时候webpack也会正确处理这部分代码，但在vite中不会，所以需要将这部分代码改成import md5 from '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 .sass
pnpm add sass -D
# .less
pnpm add stylus -D
# .styl and .stylus
pnpm add stylus -D比较巧的是，我们项目中用到的 Stylus 的 @import 别名的语法和vite冲突，@import '~@/public/stylus/mixins' 这样的代码是会报错，一开始我找到了插件，可以帮助我们解决这个问题：vite-plugin-stylus-alias，但是都后面打包的时候发现这个插件有副作用，后面采取了其他方法解决。
pnpm add vite-plugin-stylus-alias -D// vite.config.js 忽略其他代码
import vitePluginStylusAlias from 'vite-plugin-stylus-alias'
export default ({ mode }) => {
return defineConfig({
plugins: [
// ...
vitePluginStylusAlias() // 解决vite中Stylus无法使用@别名的问题
]
})
})使用这个插件会导致无法生成sourcemap文件，在打包的时候可以看到警告：Sourcemap is likely to be incorrect: a plugin (vite-plugin-stylus-alias) was used to transform files, but didn't generate a sourcemap for the transformation. Consult the plugin documentation for help，鉴于插件作者已经很久没有更新，建议能改成相对路径还是直接改，如果引用地方较多，可以定义文件为全局styl文件
最新解决方案：一般出现这个报错是因为插件使用了 vite的transformapi转换代码，但是return值缺失导致，解决方法：复制插件代码到项目中，在插件 transform 函数return的结果中，返回 map: null，然后再vite.config.js中引用项目中修改后的插件，即可完美解决，如下：文末解决bug有细说
export function imageRequirePlugin () {
return {
name: 'vite-plugin-image-require',
async transform (code) {
// 修改code.....
return {
code,
map: null // 表示源码视图不作修改
}
}
}
}
定义stylus全局文件
// vite.config.js
css: {
preprocessorOptions: {
// ...
stylus: {
imports: [resolve('src/public/stylus/mixins.styl')]
}
},
}这里需要注意，官方文档中 css-preprocessoroptions 写的是使用文件名拓展名作为key，stylus的文件拓展名是
styl，但是我使用了stylus作为key并不会有问题，相反使用styl作为key则不生效了，后续这个地方可以留意一下。在 vite源码 中，stylus和styl都进行了判断，理论上都可以使用，但目前测试的结果就是styl作为key不生效，可能源码中其他地方还能找到原因。
7. 组件库按需导入和定制主题
我们项目中用到的组件库是 Vant2，该组件库依赖Less，以及通过配置文件来定制组件的主题，在配置中我们需要进行修改：
vue-cli中的主题配置部分如下：
// vue.config.js
module.exports = {
// ...
css: {
sourceMap: !isPro, // 生成 css sourceMap
// 重定义 vant 库的主题色
loaderOptions: {
less: {
modifyVars: {
orange: '#ff8000' // 修改橘色为网站主题色
}
}
}
}
// ...
}vite中主题配置部分如下：
// vite.config.js
export default ({ mode }) => {
// ...
return defineConfig({
css: {
// 重定义 vant 库的主题色
preprocessorOptions: {
less: {
modifyVars: {
orange: '#ff8000' // 修改橘色为网站主题色
}
}
}
},
})
// ...
})按需导入
项目中按需导入vant组件库，组件可以成功导入，但是组件的样式缺失了，这是因为在webpack中，babel-plugin-import插件帮我们实现了组件的样式导入，在vite中使用 vite-plugin-style-import 插件帮我们实现这个功能，不仅vant组件库，其他诸如element、antv等组件库也可以使用这个插件进行按需导入：
yarn add vite-plugin-style-import -D// vite.config.js
import { defineConfig,loadEnv } from 'vite'
import { createStyleImportPlugin, VantResolve } from 'vite-plugin-style-import'
export default ({ mode }) => {
return defineConfig({
plugins: [
// ...
createStyleImportPlugin({ // 按需导入vant组件插件，解决vant按需导入样式丢失的问题
// resolves: [VantResolve()], // 如果是vant官方组件库，直接写这个，不需要libs，这里是我们继承了vant组件库，封装了自己的组件，所以只能通过libs来自定义导入样式
libs: [
{
libraryName: '@tw591/vant', // 自定义组件库
esModule: true,
resolveStyle: (name) => {
return `@tw591/vant/lib/${name}/style/less/`
}
}
]
})
]
})
// ...
})8. 修改alias别名配置，以及忽略文件后缀
vite配置别名的方法和vue-cli有所不同，且没有默认的别名，都需要通过配置实现，且vite默认不能忽略文件后缀导入，我们也需要通过修改配置来实现：
// vite.config.js
export default ({ mode }) => {
return defineConfig({
resolve: {
alias: [
{ find: /^~@/, replacement: resolve('src') },
{ find: 'vue$', replacement: 'vue/dist/vue.esm.js' },
{ find: '@', replacement: resolve('src') },
{ find: '_PUBLIC_', replacement: resolve('src/public') },
{ find: '_PAGES_', replacement: resolve('src/page') },
{ find: '_COMP_', replacement: resolve('src/public/components') }
],
extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue', '.less'] // 需要忽略的文件后缀
},
})
})需要注意extensions配置的顺序，从左到右进行匹配，如果存在同名但类型不同的文件，很可能得到期望外的结果，比如同目录下存在index.js和index.vue，按上面的顺序，import './index会优先匹配到index.js文件。这种情况建议补全后缀进行导入。
9. 配置前端跨域
vite配置跨域和webpack也有出入，需要修改配置
// vite.config.js
export default ({ mode }) => {
return defineConfig({
server: {
host: true,
proxy: {
'/online/api': {
target: 'https://xxx.com',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/online\/api/, '/api')
},
'/old': {
target: 'https://xxx.com',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/old/, '')
},
'/api': {
target: 'https://xxx.com',
changeOrigin: true
}
}
}
})
})以上就是几种常见的跨域配置方式，webpack中的devServer改为了server,webpack的proxy中的pathRewrite改成了rewrite，并且类型成为了函数，在函数中返回请求的路径即可。
10. 多页打包以及打包的其他配置
vite在build.rollupOptions配置多页打包，参考rollupOptions，其他配置参考文档
// vite.config.js
export default ({ mode }) => {
// ...
return defineConfig({
// ...
build: {
sourcemap: !isPro,
assetsDir: 'v2/static',
rollupOptions: {
input: {
index: resolve('index.html'),
market: resolve('market.html')
}
}
}
})
})11. 配置运行路径
base是指项目运行在服务器的哪个路径下，一般通过从环境变量中动态获取。
// vite.config.js
import { defineConfig,loadEnv } from 'vite'
export default ({ mode }) => {
function getEnv(key) {
return loadEnv(mode, process.cwd(),'')[key]
}
// ...
return defineConfig({
// ...
base: getEnv('VUE_APP_PUBLICPATH')
})
})12. 配置EsLint
vite中使用vite-plugin-eslint插件实现eslint的检查功能，安装过程中发现vite-plugin-eslint@1.4.0会报错，安装1.3.0版本即可。
yarn add vite-plugin-eslint@1.3.0 --dev// vite.config.js
import { defineConfig,loadEnv } from 'vite'
import eslintPlugin from 'vite-plugin-eslint'
export default ({ mode }) => {
return defineConfig({
// ...
plugins: [
// ...
eslintPlugin({ // eslint插件，开发时存在eslint错误组织构建并提示
cache: false,
throwOnError: !isPro // 生产环境打包不抛出异常
})
]
})
})13. 使用插件 @vitejs/plugin-legacy 兼容低版本浏览器
import legacy from '@vitejs/plugin-legacy'
export default ({ mode }) => {
plugins: [
createVuePlugin(),
legacy({
targets: ['ie >= 11'],
additionalLegacyPolyfills: ['regenerator-runtime/runtime']
})
]
})14. 配置运行指令
// package.json
{
"scripts" : {
"serve": "vite",
"bulid": "vite build",
"develop": "vite build --mode develop"
}
}可以在指令中声明mode环境，这个mode在vite.config.js中可以得到，具体可以参考前面 4. 修改环境变量
保存运行指令 npm run serve 开发环境已经可以跑起来了，但是vite的特性是你用到的页面才会进行打包，其他页面没有进行访问，是不会打包的，所以需要进行打包才能知道其他地方改造会不会有问题，打包如果有报错，再解决报错即可。
14. 解决报错
global is not defined这个错误是在
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对象，可作为备选方案。
window.global = window;@import '~@vant/icons/src/encode-woff2.less'; 报错
这个错误是vant组件库中的icon组件抛出的，vite默认不能使用别名，我们在前面配置了别名，但是配置的是
~@指向项目中的src目录，这样vant组件库的这个文件引用就找不到了。解决方法：针对vant的这个文件，做一个别名，放到第一位，优先进行匹配：
// vite.config.js export default ({ mode }) => { resolve: { alias: [ { find: /^~@vant/, replacement: resolve('node_modules/@vant') } ] } // ... })运行
vite build，css产生了一些警告。警告分为两种，一是css中的属性拼写错误，诸如：
color写成了colo，background写成了backgrounc，属于语法错误，根据警告提示搜索对应样式进行修改即可。二是一些语法正确，但还不清楚为什么压缩时提示了警告：比如 stylus 修改 scoped 样式用的
>>>语法，以及background rgba(0,0,0,0.5)提示Unexpected "rgba("。The package may have incorrect main/module/exports specified in its package.json
这个错误是通过
npm install后运行vite指令报错的，用yarn安装一直很正常，原因是node_modules的某个包的package.json定义的main入口路径错了，所以找不到模块导入。解决方法：针对这个模块，定义别名，指向正确的入口：
// vite.config.js ... alias: [ { find: 'tw591svgicon', replacement: resolve('node_modules/tw591svgicon/index.js') } ] // ...打包后导入函数定义别名后，调用函数报错
import * as minBy from 'lodash.minby'代码报错了，而且只有在生产环境下才产生。解决方法：暂时去掉别名，这应该和
lodash的导出方式modules.export在vite中转化成ES语法的过程有关系。import minBy from 'lodash.minby'require is not define， 通过require导入图片资源报错前面在步骤5已经用了插件
vite-plugin-commonjs转化common.js的代码了，require理应不会报错。但是
require导入资源图片算是webpack的功能，和js代码不一样，所以导入资源图片的代码都要进行修改：require('./images/logo.png')改成import logo from './images/logo.png'这样的修改可以兼容webpack和vite，这是在现有项目中，改动的地方会达到上百处，非常麻烦。
我们可以通过插件 vite-plugin-image-require 帮我们解决相对路径图片的导入，也就是
require('./images/logo.png')可以改动，但是绝对路径别名的导入暂时没有办法，只能通过import导入：pnpm add vite-plugin-image-require -D// vite.config.js import { imageRequirePlugin } from 'vite-plugin-image-require' export default { plugins: [ imageRequirePlugin() ], }// 相对路径 const image = require('./images/logo.png') // 绝对路径 import img from '@/assets/images/default.png'vite-plugin-image-require插件也是通过替换require为new URL实现的：vite-plugin-image-require源码 、new URL文档来自官方文档：
在生产构建时，Vite 才会进行必要的转换保证 URL 在打包和资源哈希后仍指向正确的地址。然而，这个 URL 字符串 ==必须是静态== 的，这样才好分析。否则代码将被原样保留、因而在 build.target 不支持 import.meta.url 时会导致运行时错误。// Vite 不会转换这个 const imgUrl = new URL(imagePath, import.meta.url).href // 这个是正确的 const imgUrl = new URL(`./images/${url}.png`, import.meta.url).href路径不是静态的情况下，代码被原样保留，在生产环境下会报错：
vite Failed to construct 'URL': Invalid URL，报错的原因是import.meta.url拿到undefined：issues总之，new URL不支持变量，关于new URL在vite中的更多用法以及原理还需要进一步研究。
还有一种方法可以实现动态导入：import.meta.globEager，但是这个方法同样不能使用变量，使用变量在构建时会得到
Invalid glob import syntax: pattern must start with "." or "/"错误在vue文件中的js引入css文件，打包出来顺序和webpack不一致，导致样式错乱
某个业务，用到了swiper插件，在script中导入了swiper的css：import 'swiper/css/swiper.min.css'然后再style中定义了样式覆盖
swiper.min.css中的样式：.swiper-pagination width 40px height 4px border-radius 8px left 50% margin-left -20px background #f5f5f5 $flex(row,flex-start,space-between,wrap)打包之后，发现css的顺序和webpack打包的结果不一样，导致了样式异常：
webpack:
style在import前面
vite：import在style前面这和vite解析原理有关系，现在我解决的方法是：将导入的语句放到main.js中，页面中不需要在引入这个样式文件了。
// mian.js import 'swiper/css/swiper.min.css'vite打包部署后，vant组件库代码没被编译（一脚踩进深坑）
这个问题实在太巧合了，估计没有人会遇到同样的问题。
项目在开发的过程中，vant组件库都很正常，但是
vite build打包部署到静态服务器后，页面错乱，vant组件库失效了，查看html，<van-button></van-button>这样的标签并没有被解析。为啥开发环境下没出现问题呢？？？
原因：我在vite配置中的
resolve.extensions指定了忽略文件后缀，其中包含了.less类型，但是我没留意，随意的将.less写在了配置的最前面，但是vant组件库导入组件时是只导入了文件夹，并没有指定具体文件名的，如import button from './button，而vant组件的文件目录是这样的：|-button | ... | index.js | index.less | index.css这就导致了vite在导入vant组件库，根据
extensions配置的顺序优先找到了index.less，而不是index.js，这才出现了组件库并没有导入和注册的情况！！解决方法：修改配置，把
less配置放到最后---
修改前，导致错误的配置
// ... resolve: { // ... extensions: [ '.less', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue'] }, // ...修改后，正确的顺序
// ... resolve: { // ... extensions: ['.js', '.ts', '.jsx', '.tsx', '.json', '.vue', '.less'] }, // ...error while updating dependencies
这个问题还不清楚原因，出现的原因是开发环境运行中的时候，修改了vite.config.js保存后，有几率触发这个问题（特别是错误的配置），我重启电脑后不会报错了。你可以尝试一下操作：
- 重启电脑
- 删除node_modules/.vite目录，重新运行
- 使用管理员权限运行vscode
- 删除node_modules和lock文件，重新安装
- 卸载重装pnpm并重新安装依赖
如何关闭 modulepreloads
项目是一个SPA应用，通过其他方式实现了SEO，所以需要移除modulepreloads，以减少SEO服务的负担，然而vite还没办法去除，目前有人提出了
modulepreloads的需求以及代码提交，希望后续可以有这方面的功能：modulepreloadsvite build生成Sourcemap错误
Sourcemap is likely to be incorrect: a plugin (xxxxx) was used to transform files, but didn't generate a sourcemap for the transformation. Consult the plugin documentation for help
这个错误产生的原因是：项目中的vite插件中使用到了transformAPI 转换代码，但是并没有return Sourcemap生成的方式，解决方案如下：把第三方vite插件复制到项目本地，进行修改，使用本地修改后的插件即可，我们只需要再插件的
transform函数的返回值中，加上map: null即可，如：export function imageRequirePlugin () { return { name: 'vite-plugin-image-require', async transform (code) { // 修改code..... return { code, map: null // 表示源码视图不作修改 } } } }最后，如果有条件的话，可以提交PR给插件作者，帮助其他人解决问题
后续
后面还遇到了其他坑或者新的需求等，都会更新到这里。
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。