Vue 老项目迁移至 Vite 完整指南

1. 背景与动机

随着项目规模增长，基于 Webpack 的 Vue 老项目面临以下问题：

• 项目启动时间越来越长（冷启动可能需要2-3分钟）
• 开发效率降低，特别是处理紧急问题时等待时间过长
• 模块热更新(HMR)速度变慢

Vite 作为下一代前端工具链，具有显著优势：

• 极快的服务器启动速度
• 高效的模块热更新
• 基于原生 ES 模块(ESM)的开发服务器
• 使用 Rollup 进行生产构建

2. Vite 核心原理

2.1 为什么 Vite 更快

传统打包器(如Webpack)的问题：

• 冷启动时必须抓取并构建整个应用
• 构建时间随文件数量线性增长

Vite 的优化策略：

1. 依赖预构建：

   • 使用 esbuild（Go语言编写）预构建依赖
   • 比 JavaScript 打包器快 10-100 倍
   • 处理大型依赖（如组件库）效率极高

2. 源码处理：

   • 以原生 ESM 方式提供源码
   • 浏览器按需请求，Vite 按需转换
   • 动态导入代码，只在需要时处理

3. 迁移准备

3.1 环境要求

• Vue 2.0 项目（基于 vue-cli 4.0）
• Node.js v14.18.2 或更高版本

3.2 项目结构调整

1. 将 public/index.html 移动到项目根目录
2. 修改 index.html：

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

3. 处理原模板语法问题：

   <!-- 替换前 -->
   <link rel="icon" href="<%= BASE_URL %>favicon.ico" />
   
   <!-- 替换后 -->
   <link rel="icon" href="/favicon.ico" />
   

   或通过插件处理：

   res = code.replace(/<%=\s+BASE_URL\s+%>/g, baseDir);
   

4. 具体迁移步骤

4.1 安装依赖

npm i vite vite-plugin-vue2 -S

4.2 修改 package.json

{
  "scripts": {
    "serve": "vite",
    "build": "vite build"
  }
}

4.3 配置 vite.config.js

import { defineConfig } from 'vite'
import { createVuePlugin } from 'vite-plugin-vue2'

export default defineConfig({
  plugins: [
    createVuePlugin({
      jsx: true // 兼容JSX组件
    })
  ],
  resolve: {
    extensions: ['.vue', '.js', '.ts', '.jsx', '.tsx', '.json'],
    alias: [
      { find: '@', replacement: '/src' }
    ]
  },
  server: {
    open: true,
    host: 'xxxx.jd.com',
    allowedHosts: ['.jd.com', '.jdwl.com', '.jd.co.th', '.jd.id'],
    port: 80,
    cors: true,
    proxy: {
      '/api': {
        target: 'https://xxx.jd.com',
        changeOrigin: true,
        rewrite: path => path.replace(/^\/api/, '/api')
      }
    }
  }
})

4.4 剔除 Webpack 相关依赖

• 手动删除或
• 新建 Vite 项目后迁移代码

5. 常见问题及解决方案

5.1 环境变量处理

问题：Webpack 使用 process.env，Vite 使用 import.meta.env

解决方案：

export default defineConfig({
  define: {
    'process.env': {}
  }
})

Vite 环境变量：

• import.meta.env.MODE: 应用运行模式
• import.meta.env.BASE_URL: 部署基本URL
• import.meta.env.PROD: 是否在生产环境
• import.meta.env.DEV: 是否在开发环境

5.2 global 变量问题

解决方案：在 main.ts 顶部添加 polyfill

if (typeof (window as any).global === 'undefined') {
  (window as any).global = window
}

5.3 Scss 全局变量报错

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: "$ossHostVariable: 'import.meta\u200b.env.VUE_APP_OSS_HOST';"
      }
    }
  }
})

5.4 path 模块问题

解决方案：

npm i path-browserify -S

替换引用：

import path from 'path-browserify'

5.5 require 语法问题

解决方案：使用 vite-plugin-require-transform

import requireTransform from 'vite-plugin-require-transform'

export default defineConfig({
  plugins: [requireTransform({})]
})

5.6 Vue 组件动态导入

Webpack方式：

() => import('**/**.vue')

Vite兼容方案：

const load = import.meta.glob('@/views/**/index.vue');

export const constantRoutes: any = [
  { path: '/404', component: load['404'] },
]

5.7 编译时分包策略

const SPLIT_CHUNK_CONFIG = [
  { match: /[\\/]src[\\/]_?common(.*)/, output: 'chunk-common' },
  { match: /[\\/]src[\\/]_?component(.*)/, output: 'chunk-component' },
];

const rollupOptions = {
  output: {
    chunkFileNames: 'assets/js/[name]-[hash].js',
    entryFileNames: 'assets/js/[name]-[hash].js',
    assetFileNames: 'assets/static/[name]-[hash].[ext]',
    manualChunks(id) {
      for (const item of SPLIT_CHUNK_CONFIG) {
        const { match, output } = item;
        if (match.test(id)) return output;
      }
      if (id.includes('node_modules')) {
        return id.toString().split('node_modules/')[1].split('/')[0].toString();
      }
    }
  }
};

6. 性能对比

迁移后效果：

• 冷启动时间从2-3分钟大幅降低
• 开发体验显著提升
• 首次加载时间约5秒（因浏览器需处理编译）

7. 总结

迁移关键步骤：

1. 调整项目结构（移动index.html）
2. 编写vite.config.js配置文件
3. 处理模块规范和Node环境差异

注意事项：

• 关注环境变量、全局变量、模块导入等差异
• 使用适当插件解决兼容性问题
• 调整分包策略优化构建结果

迁移后优势：

• 开发效率显著提升
• 构建流程优化
• 开发体验极大改善