记一次成功把Vue2后台项目改造成Vite2的踩坑经历

---

---

前言

公司后台项目基于@花裤衩大神的vue-element-admin，随着项目功能的不断完善和需求不断增加，项目启动也变的越来越慢。慢到什么程度呢？我i7-10代16G内存的本本跑项目最快也需要近3分钟，实在难以忍受。几经折腾，终于成功改造成了vite。现在跑项目，5秒内即可跑起来，简直不要太爽！此次改造的过程遇到很多问题，现将遇到的问题做下记录，以防后续改造类似项目时继续踩坑。

---

一、项目背景

本次要改造的是一个基于vue-element-admin的后台项目。由于项目比较老，所以没有使用到typescript，用到的element-ui和vue都还停留在2版本上。最终改造完毕后依然是跟vue3没有半毛钱关系，只是引入了vite从而大大提升编译速度。

1.1、为什么要选择Vite

其实，在选择Vite之前，我尝试过使用esbuild对项目进行优化，但优化结果并不理想。主要原因还是我太菜了[:无奈]。无奈之下，我开始尝试使用vite来优化项目。断断续续折腾了好几次，终于成功的把项目跑起来了。那速度真叫一个快，真是没有对比就没有伤害。如下图：

顺便提一嘴，如果看官想测试下项目运行所耗费的时间，可以安装一个speed-measure-webpack-plugin插件。

// 安装speed-measure-webpack-plugin
npm install speed-measure-webpack-plugin --save-dev

安装完后，修改下vue.config.js配置文件。

// 修改vue.config.js
const SpeedMeasurePlugin = require('speed-measure-webpack-plugin') // 显示编译时长
module.exports = {
   
  ......// 此处省略若干行代码
  configureWebpack: {
   
    ......// 此处省略若干行代码
    plugins: [
      ......// 此处省略若干行代码
      new SpeedMeasurePlugin(), // 此行为新增
    ],
  },
}

现在，用npm run dev命令启动项目，在项目启动成功时，终端窗口中会打印编译时长。

二、迁移前的准备

接下来分享下自己一路走来踩过的坑，我的经验可能不能完全适用于看官的项目，但有很多地方还是通用的。

2.1、补全.vue后缀

由于vite无法识别忽略扩展名的.vue文件，（参见尤大大的回复→→→import *.vue file without .vue will not work），所以我的首要工作是必须把项目中所有有导入且省略.vue文件的地方给补全后缀。虽然可以在配置resolve.extensions中加入.vue来达到目的地，但官方文档还是不建议。补全.vue后缀的这个工程量还是比较大的，共修改了快200个文件。

2.2、移动public/index.html的位置

vue2项目中的index.html文件是在根目录下的public目录中，但vite建议把index.html直接放到根目录下。相关说明→→→index.html 与项目根目录

如果项目的页面标题是唯一且不变的，可以直接在title中写死。除此之外，还需要导入入口文件main.js。

// 修改index.html
<!-- 需要修改的地方 -->
<link rel="icon" href="/favicon.ico">
<title>网页标题</title>

<script type="module" src="/src/main.js"></script>

2.2.1、通过vite-plugin-html插件来修改页面标题

除了上面的修改方式外，还可以通过安装vite-plugin-html插件来解决。

// 安装vite-plugin-html
npm install vite-plugin-html --save-dev

// 修改vite.config.js
...... // 此处省略若干行代码
import html from 'vite-plugin-html' // 为index.html提供minify和基于EJS模板功能
export default ({
     mode }) => {
   
  return defineConfig({
   
    ...... // 此处省略若干行代码
    plugins: [
      ...... // 此处省略若干行代码
      /* 新增代码开始↓↓↓ */
      html({
   
        inject: {
   
          injectData: {
   
            title: 'xxx后台管理系统',
          },
        },
      })
      /* 新增代码结束↑↑↑ */
    ],
  })
}

上面两种方式都能修改index.html文件的标题和内容，还有一些别的插件也能做到，我还没摸索过，就不写献丑了。

2.3、新建vite.config.js文件

在vue2中，项目根目录中会有一个vue.config.js的文件，现在我们要改造成vite，也得创建对应的配置文件。官方文档：→→→配置 Vite。看完官方文档后，我把vue.config.js复制了一份，并改名为vite.config.js。然后按官方的文档进行了一些简单的修改，代码如下：

// vite.config.js配置文件
/* 老代码开始↓↓↓ */
import path from 'path' // 老代码
function resolve(dir) {
   
  return path.join(__dirname, dir)
}
...... // 此处省略若干行代码
/* 老代码结束↑↑↑ */
import {
    defineConfig } from 'vite' // 此行是新增
export default ({
     mode }) => {
    // 此行是新增
  return defineConfig({
    // 此行是新增
    ...... // 老vue.config.js配置内容，实际上那些代码在这里是没有用的，需要按vite的规范来写
    /* 新代码开始↓↓↓ */
    css: {
   
      preprocessorOptions: {
   
        scss: {
   
          additionalData: `@import "/src/styles/theme.scss";`, // 挂载全局皮肤样式
        }
      }
    }
    /* 新代码结束↑↑↑ */
  })
}

从上面代码可以看出，我在一开始的时候想延续vue.config.js中的配置代码，但项目启动的时候却出现了一堆错误。而这些错误也是决定项目能否迁移成功的关键。如果看官也想改造老项目，不建议把原vue.config.js内的配置保留，应该换成对应的vite版。

2.3.1、局部安装vite

正如上面代码中第9行所写import { defineConfig } from ‘vite’，当前环境是没有安装vite的，所以第一步就是安装vite。我在项目根目录下，右键并选中Git Bash Here，此时打开了命令行窗口，也可以使用cmd进入项目目录。由于是在当前项目安装，所以我没有带-g。

// 局部安装vite
npm install vite --save-dev // 在当前项目中安装vite

2.4、安装vite-plugin-vue2

这个插件是vite官方曾提到的，因为我的项目是基于vue2的，所以就装一个吧。切换到git窗口，然后输入下方命令并回车，等待安装。

// 安装vite-plugin-vue2
npm install vite-plugin-vue2 --save-dev

安装完后要继续修改vite.config.js配置文件，修改见下方。

// vite.config.js配置文件
...... // 此处省略若干行代码
import {
    createVuePlugin } from 'vite-plugin-vue2' // Vue2支持，https://vitejs.cn/guide/features.html#vue
export default ({
     mode }) => {
   
  return defineConfig({
   
    ...... // 老vue.config.js配置内容，实际上那些代码在这里是没有用的，需要按vite的规范来写
    /* 新代码开始↓↓↓ */
    plugins: [
      createVuePlugin()
    ],
    /* 新代码结束↑↑↑ */
    ...... // 这里是上面提到的css配置
  })
}

2.5、修改package.json，添加启动命令

接着打开package.json文件，做简单的修改。

// package.json未修改前
{
   
  ...... // 原代码
  "scripts": {
   
    // "dev": "vue-cli-service serve", // 修改前
    "dev": "vite", // 修改后，也就是把原来的vue-cli-service serve换成了 vite 即可
    ...... // 省略若干行
  },
  "devDependencies": {
   
    /* 删除以@vue/cli-plugin开头的库↓↓↓ */
    "@vue/cli-plugin-babel": "4.4.4",
    "@vue/cli-plugin-unit-jest": "4.4.4",
    "@vue/cli-plugin-eslint": "4.4.4",
    /* 删除以"@vue/cli-plugin开头的库↑↑↑ */
    ...... // 省略若干行
  }
}

三、坎坷的改造之路即将开始，报错接二连三！

有必要说一下，由于项目中安装插件的完整程度和使用三方库不同的原因，下方的报错可能会存在顺序问题，也可能在看官的项目中无法复现。所以请不要较真，针对自己项目做优化就好了哈。

3.1、Failed to resolve import “@/assets/js/china.json”

前面的修改还是很简单的，接下来我便开心的切到了git窗口，输入npm run dev并回车来启动项目。还没等我反应过来，终端窗口中已显示 ready in 3460ms. 。卧槽，这也太快了吧！我带着不可思议的心情打开了浏览器，结果有报错信息存在。

// echarts有报错
[plugin:vite:import-analysis] Failed to resolve import "@/assets/js/china.json" from "src\main.js". Does the file exist?
D:/2021/work/v5_element/src/main.js:17:36
15 |  require('echarts/lib/component/title')
16 |
17 |  import china from '@/assets/js/china.json' // 引入json文件
   |                                     ^
18 |  echarts.registerMap('china', china) // 在echarts中注册使用这个文件

当时选择的是先注释掉代码，等项目跑起来了再找解决方案。友情提醒：解决方案见下面的3.11。

3.2、Failed to resolve import “styles/index.scss”

注释掉代码后，浏览器上显示新的报错信息。

// 新的报错
[plugin:vite:import-analysis] Failed to resolve import "~@/styles/index.scss" from "src\main.js". Does the file exist?
D:/2021/work/v5_element/src/main.js:20:28
18</