一次vue-cli4大项目升级到vite的经历

背景

使用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插件有关系,但开发环境的提升非常显著。

项目状况

  1. 项目中用到的Vue2,Vue Cli版本: 4.5.13,版本更新时间为 2021.5.8,vueCli4的最后版本为 4.5.17(2022.3.23),依赖的webpack版本为 ^4.0.0
  2. 组件库使用vant,依赖Less预处理器,通过vue.config.js配置设置了less主题色,在webpack仅支持less-loader@5版本以及对应的less版本
  3. 业务css预处理器为stylus: "^0.54.5",对应 stylus-loader: "^3.0.2"
  4. 进行了多页打包(MPA)
  5. 使用了workbox-webpack-plugin插件配置了PWA:WorkboxWebpackPlugin
  6. 配置了多个路径映射(alias别名)
  7. 指定了文件输出路径以及hash配置
  8. 生产环境下关闭productionSourceMap以及css的sourceMap提升打包速度
  9. proxy开启多个代理
  10. 用到了.env文件中的环境变量
  11. 按照开发规范忽略部分文件后缀以及 index.js
  12. 移除了preload脚本

期望结果

  1. 可以使用vite进行开发和打包
  2. 仍保留webpack打包功能(因为项目太大,不能保证升级到vite后会不会有问题,所以仍希望webpack原本功能正常运行)

准备工作

  1. 升级Node版本,vite只支持node12及以上,建议升级到v16以上。
  2. 安装pnpm工具,pnpm作为更好的npm依赖管理工具,是目前npm和yarn的最好替代品,且有些依赖包使用npm安装时会有异常,使用pnpm安装可解决:pnpm
  3. 小项目尝试一键转换升级:wp2vitewebpack-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. 修改环境变量

环境变量主要面临两个问题:

  1. 要兼容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

  2. vite.config.js中不能读取到环境变量

    vite.config.js是无法直接通过import.meta.envprocess.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.jsindex.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 兼容低版本浏览器

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. 解决报错

  1. 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;
  2. @import '~@vant/icons/src/encode-woff2.less'; 报错

    这个错误是vant组件库中的icon组件抛出的,vite默认不能使用别名,我们在前面配置了别名,但是配置的是~@指向项目中的 src目录,这样vant组件库的这个文件引用就找不到了。

    issues vant

    解决方法:针对vant的这个文件,做一个别名,放到第一位,优先进行匹配:

    // vite.config.js
    export default ({ mode }) => {
        resolve: {
            alias: [
                { find: /^~@vant/, replacement: resolve('node_modules/@vant') }
            ]
        }
        // ...
    })
  3. 运行 vite build,css产生了一些警告。

    警告分为两种,一是css中的属性拼写错误,诸如:color 写成了 colobackground 写成了 backgrounc,属于语法错误,根据警告提示搜索对应样式进行修改即可。

    二是一些语法正确,但还不清楚为什么压缩时提示了警告:比如 stylus 修改 scoped 样式用的 >>> 语法,以及background rgba(0,0,0,0.5)提示 Unexpected "rgba("

  4. 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') }
        ]
    // ...
  5. 打包后导入函数定义别名后,调用函数报错

    import * as minBy from 'lodash.minby' 代码报错了,而且只有在生产环境下才产生。

    解决方法:暂时去掉别名,这应该和lodash的导出方式modules.export在vite中转化成ES语法的过程有关系。

    import minBy from 'lodash.minby'

  6. 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 插件也是通过替换 requirenew 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 "/"错误

    glob-import

    issues

  7. 在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: styleimport 前面
    vite: importstyle 前面

    这和vite解析原理有关系,现在我解决的方法是:将导入的语句放到main.js中,页面中不需要在引入这个样式文件了。

        // mian.js
        import 'swiper/css/swiper.min.css'
  8. vite打包部署后,vant组件库代码没被编译(一脚踩进深坑)

    这个问题实在太巧合了,估计没有人会遇到同样的问题。

    项目在开发的过程中,vant组件库都很正常,但是vite build打包部署到静态服务器后,页面错乱,vant组件库失效了,查看html,这样的标签并没有被解析。

    为啥开发环境下没出现问题呢???

    一次vue-cli4大项目升级到vite的经历_第1张图片

    原因:我在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']
        },
    // ...
  9. error while updating dependencies
    这个问题还不清楚原因,出现的原因是开发环境运行中的时候,修改了vite.config.js保存后,有几率触发这个问题(特别是错误的配置),我重启电脑后不会报错了。

    你可以尝试一下操作:

    • 重启电脑
    • 删除node_modules/.vite目录,重新运行
    • 使用管理员权限运行vscode
    • 删除node_modules和lock文件,重新安装
    • 卸载重装pnpm并重新安装依赖
  10. 如何关闭 modulepreloads

    项目是一个SPA应用,通过其他方式实现了SEO,所以需要移除modulepreloads,以减少SEO服务的负担,然而vite还没办法去除,目前有人提出了modulepreloads的需求以及代码提交,希望后续可以有这方面的功能:modulepreloads

  11. vite 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给插件作者,帮助其他人解决问题

    transform
    source-code-transformations

后续

后面还遇到了其他坑或者新的需求等,都会更新到这里。

参考文档:

升级建议和手册

vue-cli 迁移 vite2 实践小结 - 思否社区

掘金踩坑vite文章

你可能感兴趣的:(一次vue-cli4大项目升级到vite的经历)