背景
使用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 --dev
vite-plugin-vue2 是处理vue2版本代码的插件,如果项目中是vue3,安装的依赖有所不同,请参考 webpack-to-vite
2. 复制html到根目录,并修改
⚠ 注意是复制,并只改动复制后的html,这样才不会破坏原有webpack功能。
修改复制后的html,增加对应的js文件引用,注意type属性不能少!
++ ++
多页打包(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规范的依赖,比如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的transform
api转换代码,但是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的检查功能,安装过程中发现[email protected]
会报错,安装1.3.0版本即可。
yarn add [email protected] --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插件
>[email protected]
>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,
这样的标签并没有被解析。为啥开发环境下没出现问题呢???
原因:我在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插件中使用到了transform
API 转换代码,但是并没有return Sourcemap生成的方式,解决方案如下:把第三方vite插件复制到项目本地,进行修改,使用本地修改后的插件即可,我们只需要再插件的
transform
函数的返回值中,加上map: null
即可,如:export function imageRequirePlugin () { return { name: 'vite-plugin-image-require', async transform (code) { // 修改code..... return { code, map: null // 表示源码视图不作修改 } } } }
最后,如果有条件的话,可以提交PR给插件作者,帮助其他人解决问题
后续
后面还遇到了其他坑或者新的需求等,都会更新到这里。