大型 SaaS 产品的 Vite 迁移实录：从 Webpack 到 Vite 的 6 个月演进

大型 SaaS 产品的 Vite 迁移实录：从 Webpack 到 Vite 的 6 个月演进

一、迁移背景与前期评估

该项目为面向企业客户的 SaaS 平台，前端仓库包含 32 个子应用（微前端架构），总模块数超过 6800 个。技术栈为 React 18 + TypeScript + Less，构建工具使用 Webpack 5，构建产线为 Jenkins + Docker。

迁移前的构建痛点：

• 开发服务器冷启动：单应用 45-90s，32 个应用全量启动需约 18 分钟。
• HMR 延迟：修改一行代码到浏览器热更新，平均等待 3.2s。
• 生产构建耗时：全量构建约 14.5 分钟，CI 流水线的等待时间成为交付瓶颈。
• 配置复杂度：Webpack 配置文件总量超过 3200 行，包含 18 个自定义 loader 和 24 个 plugin。

经过两周的技术评估，确定 Vite 迁移的可行性：项目以 ESM 为主（TypeScript 源码），核心依赖（React、Ant Design、ECharts）均提供 ESM 版本，不存在不可绕过的 Webpack 特有功能依赖。

二、基础迁移：配置文件对齐

2.1 resolve.alias 映射

Webpack 中大量使用了@别名指向src/目录，Vite 中通过resolve.alias等价的配置：

/** * Vite 配置文件 * * 与该项目的 Webpack 配置功能等价， * 保留所有别名映射以确保导入路径不发生变化。 */ import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import path from 'node:path'; export default defineConfig({ plugins: [ react({ // 启用 babel 以兼容部分装饰器语法 babel: { plugins: [ ['@babel/plugin-proposal-decorators', { legacy: true }], ], }, }), ], resolve: { alias: { '@': path.resolve(__dirname, 'src'), '@components': path.resolve(__dirname, 'src/components'), '@utils': path.resolve(__dirname, 'src/utils'), '@hooks': path.resolve(__dirname, 'src/hooks'), '@services': path.resolve(__dirname, 'src/services'), '@types': path.resolve(__dirname, 'src/types'), // 保留 Webpack 时期的公共组件别名 '@shared': path.resolve(__dirname, '../shared'), }, }, css: { preprocessorOptions: { less: { // 注入全局 Less 变量，等价于 Webpack 的 style-resources-loader additionalData: ` @import '@/styles/variables.less'; @import '@/styles/mixins.less'; `, javascriptEnabled: true, }, }, modules: { // CSS Modules 命名规则与 Webpack 保持一致 localsConvention: 'camelCaseOnly', generateScopedName: '[name]__[local]___[hash:base64:5]', }, }, });

2.2 环境变量兼容

Webpack 通过process.env.XXX注入环境变量，Vite 使用import.meta.env.XXX。迁移阶段采用兼容性中间层：

/** * 环境变量兼容层 * * 统一提供 process.env 的访问方式， * 平滑过渡到 import.meta.env，减少业务代码改动。 * * 使用方式：在入口文件最顶部引入 * import './env-compat'; */ // src/env-compat.ts if (typeof process === 'undefined' || !process.env) { (globalThis as Record<string, unknown>).process = { env: {} as Record<string, string>, }; } // 将 Vite 环境变量映射到 process.env 上 const envKeys = Object.keys(import.meta.env); for (const key of envKeys) { if (key.startsWith('VITE_')) { // 移除 VITE_ 前缀以保持与 Webpack 时期一致 const legacyKey = key.replace(/^VITE_/, ''); (process.env as Record<string, string>)[legacyKey] = ( import.meta.env as Record<string, string> )[key]; } }

2.3 require 语法的处理

项目中存量代码中存在require.context和动态require的情况。对于自动化加载场景（如自动注册全局组件、自动导入路由），使用import.meta.glob替代：

/** * Webpack require.context → Vite import.meta.glob 迁移 * * 原始代码（Webpack）: * const modules = require.context('./modules', true, /\.tsx$/); * modules.keys().forEach(key => { ... }); * * 迁移后（Vite）: */ const modules = import.meta.glob<{ default: React.ComponentType }>( './modules/**/*.tsx', { eager: true } ); // 保持与原有 API 一致的使用方式 for (const [path, module] of Object.entries(modules)) { const componentName = path .replace('./modules/', '') .replace(/\.tsx$/, '') .replace(/\//g, '_'); registerComponent(componentName, module.default); }

三、深度适配：自定义 Vite 插件

3.1 微前端子应用的构建适配

项目基于 qiankun 的微前端架构，子应用需要导出bootstrap、mount、unmount生命周期。Vite 的默认构建产物格式为 ESM，而 qiankun 需要通过window全局访问子应用，因此需要自定义构建配置：

/** * Vite 插件：微前端子应用构建适配 * * 确保构建产物符合 qiankun 的加载要求： * 1. 格式为 UMD（通过 window 导出） * 2. 入口 JS 和 CSS 文件名可预测（用于主应用动态加载） * 3. publicPath 在运行时动态注入 */ import type { Plugin } from 'vite'; interface MicroAppPluginOptions { /** 子应用名称，用于 window 挂载 */ appName: string; /** 构建目标，默认 es2015 */ target?: string; } export function microAppPlugin(options: MicroAppPluginOptions): Plugin { const { appName, target = 'es2015' } = options; return { name: 'vite-plugin-micro-app', config(config) { return { ...config, base: `//cdn.example.com/micro-apps/${appName}/`, build: { ...config.build, target, // 类库模式构建，以 UMD 格式暴露 lib: { entry: 'src/index.tsx', name: appName, formats: ['umd'], fileName: () => 'index.js', }, rollupOptions: { // 排除主应用提供的公共依赖 external: ['react', 'react-dom', 'antd', 'moment'], output: { globals: { react: 'React', 'react-dom': 'ReactDOM', antd: 'antd', moment: 'moment', }, assetFileNames: 'index.[ext]', }, }, }, }; }, // 在 HTML 中注入 publicPath 动态设置逻辑 transformIndexHtml(html) { return html.replace( '</head>', `<script> // 动态设置 publicPath，支持不同环境部署 if (window.__POWERED_BY_QIANKUN__) { __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__; } </script></head>` ); }, }; }

3.2 SVG 图标组件的兼容

原 Webpack 配置中使用@svgr/webpack将 SVG 文件作为 React 组件导入。Vite 中对应使用vite-plugin-svgr插件，确保导入方式完全一致。

3.3 传统构建产物的兼容处理

项目中有 3 个老旧依赖使用 AMD 格式且不提供 ESM 版本。通过编写 Vite 插件在transform阶段做代码转换，将 AMD 的define包装转换为 ESM 格式。

四、性能对比与优化

4.1 核心指标对比

4.2 拆包优化策略

Vite/Rollup 的默认拆包策略比较保守，针对大型 SaaS 应用需要手动配置拆包策略以获得更优的缓存命中率：

/** * 自定义拆包策略 * * 目标：将第三方依赖按更新频率分层， * 最大化浏览器缓存利用率。 */ // vite.config.ts 的 build.rollupOptions.output.manualChunks manualChunks(id: string) { // 框架层：React 生态，更新频率最低 if (id.includes('node_modules/react') || id.includes('node_modules/react-dom') || id.includes('node_modules/react-router')) { return 'framework'; } // UI 层：Ant Design，中等更新频率 if (id.includes('node_modules/antd') || id.includes('node_modules/@ant-design')) { return 'antd'; } // 图表层：ECharts，体积大但更新频率低 if (id.includes('node_modules/echarts') || id.includes('node_modules/zrender')) { return 'echarts'; } // 工具层：lodash/moment/dayjs，更新频率较低 if (id.includes('node_modules/lodash') || id.includes('node_modules/moment') || id.includes('node_modules/dayjs')) { return 'utils'; } // 业务公共代码：体积适中，与业务迭代同步更新 if (id.includes('src/shared') || id.includes('src/common')) { return 'common'; } // 其余第三方依赖 if (id.includes('node_modules')) { return 'vendor'; } }

4.3 迁移中的意外发现

迁移完成后的一次 Code Review 中，发现 Webpack 时期的ts-loader配置中transpileOnly: true开启了，但对应的fork-ts-checker-webpack-plugin却在某次升级中意外失效。这意味着项目在过去 4 个月中，CI 没有执行完整的类型检查。

切换到 Vite 后，团队同时引入vite-plugin-checker确保类型检查在开发和 CI 阶段始终有效。这一问题也直接促成了 CI 流水线中增加独立的tsc --noEmit检查步骤。

五、总结

六个月、32 个子应用、6800+ 模块的迁移，技术决策的核心经验：

1. 渐进式迁移优先：先迁移一个中等复杂度的子应用作为样板，积累配置模板和踩坑经验后再推广，避免全面铺开导致的风险。
2. 兼容性优先于彻底性：环境变量兼容层、别名映射等"过渡代码"在迁移阶段是必要的。彻底废弃旧模式应该安排在迁移稳定后作为独立迭代进行。
3. 迁移是质量检查的机会：在迁移过程中发现的类型检查缺失、废弃依赖等问题，应当作为迁移任务的一部分一并解决。
4. 灰度发布不可省略：通过特性开关（Feature Flag）控制新旧构建产物的下发比例，先覆盖内部用户，逐步扩大到外网全量，是风险最低的切换方式。

在 Vite 6（基于 Rolldown）正式稳定后，还可以考虑进一步迁移到 Rolldown 获得更快的生产构建速度。这将是下一个迭代周期的话题。