vue2迁移到vite[保姆级教程]
vue2迁移到vite[保姆级教程]
- 使用vue CLI创建项目
- 进行vite迁移详细步骤
- 1. 安装 Vite 和 Vue 2 支持插件
- 2. 创建 vite.config.js
- 3. 修改 package.json 脚本
- 4. 创建 index.html
- 5. 确保 main.js 正确引入
- 6. 处理静态资源
- 7. 构建优化（可选）
- 8. 启动项目
- 常见问题解决
- 拓展：彻底告别 Webpack
将
Vue 2项目迁移到Vite是一个非常明智的选择，因为 Vite 提供了更快的启动速度和热更新。不过，由于 Vite 原生支持的是 Vue 3，因此需要一些额外配置来支持 Vue 2。
本文将使用一个干净的vue2 CLI创建项目进行演示，你也可按照以下步骤进行操作：
使用vue CLI创建项目
使用 Vue CLI 创建 Vue 2 + JS 项目：vue create 项目名称，以下截图为创建项目时的具体选项：
项目创建完成后，接下来对这个项目进行vite迁移
进行vite迁移详细步骤
1. 安装 Vite 和 Vue 2 支持插件
npm install --save-dev vite vite-plugin-vue2
如果你使用了 JSX，再加：
npm install --save-dev @vitejs/plugin-vue2-jsx
2. 创建 vite.config.js
在项目根目录创建 vite.config.js：
// vite.config.js
import { defineConfig } from 'vite'
// import vue2 from 'vite-plugin-vue2' // 错误写法：因为它没有 module.exports = function() {} 这种默认导出
import { createVuePlugin } from 'vite-plugin-vue2' // 正确写法
import { resolve } from 'path'export default defineConfig({plugins: [createVuePlugin() // 启用 Vue 2 支持],// 别名配置（和 Vue CLI 一致）resolve: {alias: {'@': resolve(__dirname, 'src'),'@components': resolve(__dirname, 'src/components'),'@views': resolve(__dirname, 'src/views')// 可根据需要添加更多}},// 开发服务器配置server: {host: '0.0.0.0', // 允许局域网访问port: 3000, // 默认端口open: true, // 启动时自动打开浏览器proxy: {// 如果有 API 接口需要代理，例如：// '/api': {// target: 'http://localhost:8080',// changeOrigin: true,// rewrite: (path) => path.replace(/^\/api/, '')// }}},// 构建输出目录（与 Vue CLI 一致）build: {outDir: 'dist',assetsDir: 'static' // 资源文件夹},// SCSS 全局变量注入（可选，非常实用）css: {preprocessorOptions: {scss: {// 引入全局变量和 mixin// additionalData: `// @import "@/styles/variables.scss";// @import "@/styles/mixins.scss";// `}}}
})
3. 修改 package.json 脚本
替换原来的 vue-cli-service 命令：
"scripts": {"serve": "vue-cli-service serve","build:serve": "vue-cli-service build","vite": "vite","build": "vite build","preview": "vite preview","lint": "vue-cli-service lint"
}
拓展：可以使用
npm run serve，项目迁移完成后可自行选择是否卸载webpack，卸载可以减少项目体积，
卸载命令：npm uninstall @vue/cli-service，执行后，你就无法再使用 webpack 启动项目了。
具体可阅读下文：彻底告别 Webpack
4. 创建 index.html
Vite 需要一个入口index.html文件放在 public/ 或项目根目录(推荐)。
<!-- 项目根目录 -->
<!-- index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>Vue 2 + Vite</title>
</head>
<body>
<div id="app"></div>
<!-- 关键：使用 type="module" 引入 main.js -->
<script type="module" src="/src/main.js"></script>
</body>
</html>
✅ 注意：
<script type="module" src="/src/main.js"></script>是关键，Vite 通过它启动应用。- 不需要手动引入 Vue 或其他库，由打包系统处理。
5. 确保 main.js 正确引入
你的 src/main.js 应该类似这样：（通常无需改）
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'// 如果你使用了 Element UI、Vue Router 等，也需要在这里引入Vue.config.productionTip = falsenew Vue({router,store,render: h => h(App)
}).$mount('#app')
6. 处理静态资源
- 将
public下的静态资源保留。 src/assets中的资源可以通过@/assets/xxx引用。
7. 构建优化（可选）
如果你使用了 Vuex、Vue Router，无需更改，它们在 Vue 2 中仍然可用。
8. 启动项目
npm run vite
浏览器自动打开，页面正常显示 ✅
你现在可以愉快地享受 Vite 带来的 飞快启动 和 极速热更新 了！⚡
如果后续遇到路由、静态资源、环境变量等问题，也欢迎提问！
常见问题解决
Vue 2 不支持 <script setup>：除非你使用unplugin-vue2-script-setup插件。
兼容性问题：某些依赖可能不兼容 ESM，可在 vite.config.js 中配置 optimizeDeps 或 resolve.alias。
环境变量：Vite 使用 import.meta.env，而不是 process.env。你可以通过 .env 文件定义。
推荐 .env 示例：
创建 .env.development文件：
# .env.development
VITE_APP_API_URL=http://localhost:3000/api
创建 .env.production文件：
# .env.production
VITE_APP_API_URL=https://api.example.com
✅ 提示：Vite 只会暴露 VITE_ 开头的变量。
在代码中使用：
console.log(import.meta.env.VITE_APP_API_URL)
拓展：彻底告别 Webpack
当你执行：
npm uninstall @vue/cli-service
之后，你就 无法再使用 webpack 启动项目了。
🔍 详细解释
1. @vue/cli-service 是什么？
它是 Vue CLI 的核心运行时，提供了以下命令：
npm run serve→ 启动 Webpack 开发服务器npm run build→ 使用 Webpack 打包项目npm run lint
这些功能都由@vue/cli-service内部集成的 Webpack、Babel、ESLint 等工具提供支持。
2. 卸载后会发生什么？
| 操作 | 结果 |
|---|---|
| npm uninstall @vue/cli-service | 删除了 Webpack 构建系统 |
| 执行 npm run serve | 报错：vue-cli-service: command not found |
| Webpack 功能 | 完全消失 |
3.卸载它有什么好处？
| 好处 | 说明 |
|---|---|
| 🔽 减少 node_modules 体积 | @vue/cli-service 及其依赖很大（~100MB+） |
| 🔐 减少依赖冲突风险 | 少一个大型构建系统，项目更干净 |
| 🧹 明确技术栈 | 表明你已正式切换到 Vite，避免团队混淆 |
| ⚡ 提升安装速度 | npm install 更快 |
🧹 清理残留配置（可选）
为了“断干净”，你可以删除或保留以下文件：
| 文件 | 是否可以删除 | 说明 |
|---|---|---|
| babel.config.js | ✅ 可删 | Vite 也支持 Babel，但通常不需要单独配置 |
| vue.config.js | ✅ 可删 | Vue CLI 的配置，Vite 不读取它 |
| public/index.html | ❌ 不要删 | 如果你还用它作为静态资源目录 |
| .browserslistrc | ✅ 可留 | 影响 Babel 和 PostCSS，Vite 也会用到 |
💡 建议保留 .browserslistrc，因为它影响 CSS 兼容性处理。
🔄 如果你想临时切回 Webpack
万一哪天你想再用 Webpack，可以重新安装：
npm install --save-dev @vue/cli-service
然后就能继续使用：
npm run serve # Webpack 启动
npm run build # Webpack 打包
但注意：两个构建系统共存可能带来混淆，建议 专注使用 Vite。
最后：如果你遇到具体错误，欢迎贴出，我可以帮你针对性解决！