如何从 Vue CLI 迁移到 Vite

注：本文翻译而来，并做少许改动，原文地址：https://vueschool.io/articles/vuejs-tutorials/how-to-migrate-from-vue-cli-to-vite/

如果您在 2021 年之前一直在使用 Vue 进行开发，那么您选择的构建工具很有可能是 Vue CLI。 一段时间以来，它一直是 Vue.js 项目脚手架的事实标准。 不过现在，Evan You 的下一代构建工具 Vite 已经引起了很多关注，并且是 Vue CLI 的一个很好的替代品。

为什么要从 Vue CLI 迁移到 Vite？

进行迁移的主要原因是速度。 Vite 的开发服务器速度很快。 因为它使用原生浏览器支持 JavaScript 模块，所以服务器启动时间是即时的。 该方法还意味着无论应用程序的大小如何，热模块更换都保持快速，因为不必重新构建整个包。

为了演示，这里是一个全新的 Vue CLI 项目与使用 Vite 的完全相同的项目相比的基准。

• 启动时间：
  • Vue CLI - 2591 毫秒（超过 2 秒）
  • Vite - 259 毫秒（不到半秒 - 快 10 倍）⚡️
• 热模块更换 (HMR)：
  • Vue CLI - 171 毫秒
  • Vite - 不是由 Vite 打印到控制台，而是通过观察…基本上是即时的

请记住，这只是脚手架样板。 随着项目的增长，Vue CLI 版本会逐渐变慢，而 Vite 承诺无论项目规模如何，都能以相同的水平执行。

如何从 Vue CLI 迁移到 Vite

如果你确信 Vite 适合你，你如何将你的项目从使用 Vue CLI 迁移到 Vite？

为了回答这个问题，我使用 Vue CLI 构建了一个全新的项目，我将与您一起完成将其转换为 Vite 的步骤。 当然，您通常不会从一个全新的 Vue CLI 项目开始，但其中许多步骤对于您已建立的项目来说都是相同的。

另外，我选择使用 Vue 2 代码库，因为你们中的大多数人可能仍然在 Vue 2 上运行完善的代码库。但是，我还在下面的过程中做了注释，其中 Vue 3 的情况会有所不同。

最后，如果你不想和我一起走过整个过程，你可以在这个示例 repo 中看到变化的差异。

步骤1：更新依赖

迁移到 Vite 的第一步是更新 package.json 中的依赖项。 我们需要删除与 Vue CLI 相关的依赖项。

// package.json
"@vue/cli-plugin-babel": "~4.5.0", // remove
"@vue/cli-plugin-eslint": "~4.5.0", // remove
"@vue/cli-plugin-router": "~4.5.0", // remove
"@vue/cli-plugin-vuex": "~4.5.0", // remove
"@vue/cli-service": "~4.5.0", // remove

我们还可以删除 sass-loader，因为 Vite 内置支持最常见的开箱即用预处理器。 这将允许我们继续使用我们选择的 CSS 预处理器。 请注意，Vite 建议将原生 CSS 变量与实现 CSSWG 草案的 PostCSS 插件一起使用，并编写简单的、符合未来标准的 CSS。

// package.json
"sass-loader": "^8.0.2" // remove

最后，我们将添加 Vite 作为依赖项，以及 Vite 的 Vue 插件组件，以支持单文件组件。

// package.json
"@vitejs/plugin-vue": "^1.6.1",
"vite": "^2.5.4",

此外，由于我们正在迁移 Vue 2 项目，除了官方 Vue 插件之外，我们还需要包含社区维护的 Vue 2 Vite 插件。 如果我们使用 Vue 3，这将是不必要的。

// package.json
"vite-plugin-vue2" : "1.9.0" // add for Vue 2

安装 Vite 插件后，我们现在还可以删除由 Vite Vue 插件处理的 vue 模板编译器。

// package.json
"vue-template-compiler": "^2.6.11" //remove (SFC support provided by vite vue plugin)

步骤2: 仅提供对主流浏览器的支持

由于 Vite 是下一代构建工具，让我们乐观地只支持最新的浏览器。 这将使我们的构建尽可能精简和快速。

实际上，这意味着我们可以完全从依赖项中移除 Babel，因为大多数移动和桌面新版本浏览器几乎完全支持所有 ES6 功能。 如果您仍然需要支持Internet Explorer 11等旧版浏览器，Vite 确实为此提供了官方插件。

所以，要删除 Babel，首先我们要删除 babel.config.js 文件。

接下来，由于我们已经删除了需要 babel 本身的 @vue/cli-plugin-babel 依赖项，我们只需要从 package.json 中删除其他几个 babel 相关的依赖项。

// package.json
"babel-eslint": "^10.1.0", // remove
"core-js": "^3.6.5", // remove

随着 babel-eslint 现在被移除，我们需要将它作为解析器从我们的 .eslintrc 文件中移除。

// .eslintrc
// remove
parserOptions: {
    parser: "babel-eslint",
},

注意：如果您的项目中没有 linting/formatting 设置，您可以跳到下一步，但如果您还没有，我强烈建议您添加它。 这是一个很好的教程，用于在您的 Vite 驱动的 Vue 项目上进行设置。

最后，当我们在 .eslintrc 中时，我们需要将环境从 node 更新到 es2021，因为我们只支持那些常青浏览器。

// .eslintrc
env: {
    node: true, // remove
    es2021: true,
}

这种变化也会迫使我们更新 eslint 本身，以及 eslint-plugin-vue 以支持 es2021 环境。

$ npm install eslint@8 eslint-plugin-vue@8

步骤3：添加Vite配置

在这一步中，让我们为我们的 Vue.js 项目配置 Vite。 Vite 通过项目根目录下的 vite.config.js 文件进行配置。 这是使用 npm init vite@latest 为 Vue 生成全新的 Vite 项目时默认的 vite.config.js 文件的样子。

// vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()]
})

我们将要添加 2 更多的东西。

首先，我们将从 vite-plugin-vue2 导入 Vue 插件，而不是官方的 Vite Vue 插件。

// vite.config.js
import vue from '@vitejs/plugin-vue' // remove
import { createVuePlugin as vue } from "vite-plugin-vue2";

//...

如果您使用的是 Vue 3，当然，您不必这样做。

其次，为了让 @import 别名像在 Vue CLI 中一样工作，我们需要添加这个位。

// vite.config.js
//...
const path = require("path");
export default defineConfig({
  //...
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

步骤4：移动index.html

与 Vue CLI 不同，Vite 实际上将保存 Vue.js 应用程序的 index.html 文件放在项目的根目录而不是公共目录中，因此您需要移动它。

在 index.html 中，您还需要进行一些更改。

首先，我们将 <%= htmlWebpackPlugin.options.title %> 占位符的实例更改为硬编码值。

// index.html

<!--remove-->
<title><%= htmlWebpackPlugin.options.title %></title> 
<!--add-->
<title>Hard Coded Title</title>

//...
<!--remove-->
<strong>We're sorry but <%= htmlWebpackPlugin.options.title %> doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
<!--add-->
<strong>We're sorry but this app doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>

我们还需要用绝对路径替换 <%= BASE_URL %> 占位符。

// index.html

<!--remove-->
<link rel="icon" href="<%= BASE_URL %>favicon.ico">
<!--add-->
<link rel="icon" href="/favicon.ico">

最后也是最重要的一点，JavaScript 应用程序不再是自动注入的，所以我们需要像这样包含它：

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

步骤5：更新脚本

回到 package.json 我们还需要更新脚本。 我们会将旧的 vue-cli-service 命令更改为 Vite 特定命令。

// package.json
"serve": "vue-cli-service serve", // remove
"build": "vue-cli-service build", // remove
"dev": "vite",
"build": "vite build",
"serve": "vite preview",

请注意，启动开发服务器的命令不再提供。 Vite 使用 dev 代替， serve 用于在本地预览生产构建。

此外，如果您启用了 lint，您应该更新 lint 脚本以直接运行 eslint。

"lint": "eslint --ext .js,.vue --ignore-path .gitignore --fix src"

步骤6：更新环境变量

环境变量在 Vite 中的工作方式与它们在 Vue CLI 中的工作方式之间有很多交叉。 例如，您的 .env 命名约定可以保持不变。

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

但是，您不能再访问流程变量上的环境变量。 相反，它们可以在 import.meta.env 上找到。

// router/index.js
base: process.env.BASE_URL, //remove
base: import.meta.env.BASE_URL,

此外，用于使声明客户端暴露的环境变量更明显的 VUE_APP_ 前缀已更改为 VITE_，因此如果您有任何此类环境变量，则必须相应地更新它们。

步骤7：为 SFC 导入添加 .vue 扩展名

虽然我们新创建的 Vue CLI 项目已经这样做了，但我敢打赌，您现有的应用程序可能不会这样做。 因此，您必须确保单个文件组件的所有导入都以 .vue 扩展名结尾。

// Home.vue
import HelloWorld from "@/components/HelloWorld.vue"; // .vue is required

如果由于代码库的大小而导致此过程过于繁重，您可以配置 vite，这样就不需要了。 这是通过将 .vue 添加到 vite.config.js 中的 resolve.extensions 配置选项来完成的。 确保您还手动包含所有默认扩展名，尽管此选项会覆盖默认值。

// vite.config.js
//...
export default defineConfig({
  plugins: [vue()],
  resolve: {
    extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue'],
    //...
  },
});

虽然这可行，但应尽可能避免。 为什么？ 因为根据 Vite 文档：“请注意，不建议省略自定义导入类型（例如 .vue）的扩展，因为它会干扰 IDE 和类型支持。”

步骤8：清理魔法注释

最后，您可以删除所有用于命名动态导入的神奇注释，因为这些是特定于 webpack 的注释，对 Vite 没有任何意义。

// router/index.js
import(
    /* webpackChunkName: "about" */  // remove
    "../views/About.vue"
),

相反，Vite 会根据原始 .vue 文件名和缓存破坏哈希自动命名您的块，如下所示：About.37a9fa9f.js

步骤9：享受更快、更无缝的开发体验

完成上述步骤 1-8 后，您的应用程序应该可以开始使用 Vite 运行了！ 继续用 npm run dev 启动你的开发服务器，看看 Vite 对你自己来说有多快。

如果此时您有任何其他错误弹出，请在下面发表评论并与社区分享，以及您可能为他们提供的任何解决方案！

最后，请记住，您可以在此示例存储库中查看所有更改差异，以帮助您进行迁移。