一、为什么要迁？我们当时的痛点

项目技术栈：React 18 + TypeScript + Ant Design + less。Webpack 配置经过多人 “迭代”，已经变得极其复杂：各种 loader、plugin、alias、proxy，还有自定义的打包分析脚本。

痛点：

• 开发服务器启动：45 秒起步，同事可以泡杯咖啡
• 热更新：改一行代码，等待 3 秒才刷新
• 生产构建：6 分钟，CI 经常超时
• 配置维护：没人敢动 webpack.config.js，一动就崩

我们调研了 Vite，开发服务器启动秒级、HMR 极快、配置简单。决定迁移。

二、迁移过程与踩坑记录

坑 1：环境变量不兼容

Webpack 用process.env注入变量，Vite 用import.meta.env。全局搜索替换容易遗漏，特别是第三方库中使用了process.env。

解决：用@vitejs/plugin-react自带的define配置，手动映射：

// vite.config.js
export default defineConfig({
  define: {
    'process.env': process.env
  }
})

但这样会打包所有环境变量，有安全风险。建议只映射需要的：'process.env.API_URL': JSON.stringify(process.env.API_URL)。

坑 2：CommonJS 模块不兼容

Vite 默认只支持 ESM，但node_modules里有大量 CommonJS 模块。比如@ant-design/charts、moment等。

现象：提示Module not found或require is not defined。

解决：

1. 先用vite-plugin-commonjs（已废弃），官方推荐optimizeDeps.include： js optimizeDeps: { include: ['@ant-design/charts', 'moment'] }
2. 实在不行，在build.rollupOptions中配置@rollup/plugin-commonjs。

坑 3：less 全局变量失效

Webpack 中我们用less-loader的modifyVars全局注入主题变量。Vite 不支持这种写法。

解决：用vite-plugin-style-import或直接修改 vite 配置的 css 预处理器选项：

css: {
  preprocessorOptions: {
    less: {
      modifyVars: { '@primary-color': '#1890ff' },
      javascriptEnabled: true
    }
  }
}

但这样只对组件库有效，自己写的 less 文件还需要手动@import全局变量文件。

坑 4：动态导入路径问题

代码中大量使用import(@/pages/${pageName}/index)动态导入。Vite 要求动态路径必须静态可分析。

现象：构建时提示The requested module '...' does not provide an export named 'default'。

解决：改用const modules = import.meta.glob('./pages/**/index.tsx')，然后手动匹配。

坑 5：代理重写规则不一致

Webpack 的devServer.proxy和 Vite 的server.proxy配置方式不同，特别是路径重写和 Cookie 的secure选项。

解决：仔细对照文档，测试所有接口。我们花了大半天才把所有代理规则调通。

坑 6：多页应用配置

我们的项目是多页应用（多个入口）。Webpack 用entry: { a: './src/a.tsx', b: './src/b.tsx' }，Vite 原生不支持多页。

解决：使用vite-plugin-html或手动配置build.rollupOptions.input：

build: {
  rollupOptions: {
    input: {
      a: resolve(__dirname, 'src/a.html'),
      b: resolve(__dirname, 'src/b.html')
    }
  }
}

坑 7：生产构建后路由 404

Vite 构建后，HTML 中的资源路径默认是绝对路径/assets/...，如果部署在子目录下会 404。

解决：设置base: './'（相对路径）或根据部署路径动态设置。

三、迁移后的收益

经过两周折腾，我们终于成功迁移。对比数据：

团队开发体验大幅提升，同事不再抱怨 “等编译”。

四、迁移建议

如果你也在考虑迁移，几点建议：

1. 评估项目复杂度：如果项目大量使用 Webpack 特有插件（如DefinePlugin、ProvidePlugin），迁移成本高。
2. 先跑 demo：拿一个最小模块试水，验证可行性。
3. 渐进迁移：不用一次性全切，可以先用 Vite 开发，生产构建仍用 Webpack，逐步替换。
4. 备好回滚方案：迁移期间保留原 Webpack 配置，出问题随时切回。
5. 团队培训：Vite 的 HMR 机制、环境变量、动态导入与 Webpack 不同，团队要统一学习。

五、最后

Vite 不是银弹，但它确实解决了 Webpack 在开发体验上的痛点。如果你的项目也深受启动慢、热更新卡顿的困扰，不妨一试。

你们团队在用 Vite 吗？迁移中遇到过什么坑？点个赞让更多需要的人看到。