从 Webpack 迁移到 Vite：踩坑清单和性能对比
Migrating from Webpack to Vite: Pitfall Checklist and Performance Comparison
| Sophia Li | 2026-08-11T08:16:30
花了一周把项目从 Webpack 5 迁移到了 Vite 6，构建速度快了 10 倍。这篇记录迁移中遇到的所有坑。
Migrated a project from Webpack 5 to Vite 6 in one week with 10x build speed improvement. Documenting all pitfalls encountered.
## 为什么迁移 我们的管理后台项目用的 Webpack 5，300+ 个组件，冷启动 `npm run dev` 要 **45 秒**，HMR 修改一个文件要等 **3-5 秒**。开发体验太差了。 Vite 基于 ESM 原生模块，开发模式下不需要打包，理论上启动速度应该快很多。 ## 迁移步骤 ### 1. 安装 Vite ```bash npm install -D vite @vitejs/plugin-react npm uninstall webpack webpack-cli webpack-dev-server ``` ### 2. 创建 vite.config.ts ```typescript import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import path from 'path'; export default defineConfig({ plugins: [react()], resolve: { alias: { '@': path.resolve(__dirname, 'src') }, }, server: { port: 3000 }, }); ``` ### 3. 修改 index.html Webpack 用 `HtmlWebpackPlugin` 注入 JS，Vite 需要在 HTML 里直接引用： ```html ``` ## 踩坑清单 **坑 1：require() 不可用** Vite 开发模式用的是 ESM，不支持 CommonJS 的 `require()`。全局搜索替换： ```javascript // Before const logo = require('./assets/logo.png'); // After import logo from './assets/logo.png'; ``` 全项目有 47 处 `require()`，逐个改完。 **坑 2：环境变量前缀不同** ```bash # Webpack: REACT_APP_ 前缀 REACT_APP_API_URL=https://api.example.com # Vite: VITE_ 前缀 VITE_API_URL=https://api.example.com ``` 代码里的 `process.env.REACT_APP_XXX` 全部替换成 `import.meta.env.VITE_XXX`。 **坑 3：SVG 导入方式变了** ```javascript // Webpack + SVGR import { ReactComponent as Logo } from './logo.svg'; // Vite + vite-plugin-svgr import Logo from './logo.svg?react'; ``` 需要安装 `vite-plugin-svgr` 并在配置里添加。 **坑 4：CSS Modules 命名** Webpack 默认把 `.module.css` 当作 CSS Modules，Vite 也是，但类名生成规则不同。如果有 E2E 测试依赖了类名选择器，可能会挂。 **坑 5：动态 import 的路径** ```javascript // Webpack 支持 const Component = lazy(() => import(`./pages/${name}`)); // Vite 需要用 import.meta.glob const pages = import.meta.glob('./pages/*.tsx'); const Component = lazy(pages[`./pages/${name}.tsx`]); ``` **坑 6：Node.js polyfill** Webpack 5 虽然移除了自动 polyfill，但很多项目还是手动加了。Vite 里需要用 `vite-plugin-node-polyfills`。 **坑 7：proxy 配置语法** ```javascript // Webpack (webpack.config.js) devServer: { proxy: { '/api': 'http://localhost:8080' } } // Vite (vite.config.ts) server: { proxy: { '/api': 'http://localhost:8080' } } ``` 语法几乎一样，但 Vite 的 proxy 基于 `http-proxy`，某些高级配置（如 `onProxyReq`）的参数格式略有不同。 ## 性能对比 | 指标 | Webpack 5 | Vite 6 | 提升 | |------|-----------|--------|------| | 冷启动 | 45s | 1.8s | 25x | | HMR | 3-5s | <100ms | 30-50x | | 生产构建 | 120s | 12s | 10x | | 构建产物大小 | 2.8MB | 2.6MB | -7% | 冷启动从 45 秒到 1.8 秒，这个提升是革命性的。HMR 基本感觉不到延迟。 ## 总结 迁移总共花了一周。主要工作量在 `require()` 替换和环境变量迁移上。建议分模块逐步迁移，不要一次性全改。 如果你的 Webpack 项目启动超过 10 秒，强烈建议迁移到 Vite。
Migrated a 300+ component React admin panel from Webpack 5 to Vite 6. Key pitfalls: require() to ESM imports (47 instances), environment variable prefix change (REACT_APP_ to VITE_), SVG import syntax, dynamic import patterns, and Node.js polyfills. Results: cold start 45s→1.8s (25x), HMR 3-5s→<100ms (30-50x), production build 120s→12s (10x).