Vite + React 项目构建慢或包体大时…

适用于 Vite + React 应用的构建配置、代码分割、依赖管理与包体积/构建性能优化。

适用场景

解决思路

1. 避免 barrel file 导入：不要从 `index.ts` 聚合文件导入，改为从具体文件直接导入，例如 `import { Button } from '@/components/Button'`；图标库用深路径导入，例如 `import Check from 'lucide-react/dist/esm/icons/check'`；可安装 `vite-plugin-barrel`，在 `vite.config.ts` 的 `plugins` 中配置 `barrel({ packages: ['lucide-react', '@mui/material', '@mui/icons-material'] })`，在构建时把 barrel 导入改写为直接导入；常见受影响库包括 `lucide-react`、`@mui/material`、`@mui/icons-material`、`@tabler/icons-react`、`react-icons`、`@radix-ui/react-*`、`lodash`、`date-fns`、`rxjs`。
2. 配置 manualChunks 拆分 vendor：在 `vite.config.ts` 的 `build.rollupOptions.output.manualChunks` 中按库分组，例如 `vendor-react: ['react', 'react-dom']`、`vendor-router: ['react-router-dom']`、`vendor-query: ['@tanstack/react-query']`、`vendor-ui: ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu']`；也可用函数形式 `manualChunks(id)`，检查 `id.includes('node_modules')`，按 `react-dom`、`react-router`、`@tanstack` 返回对应 chunk 名，其余归入 `vendor`。
3. 动态导入做路由级代码分割：用 `React.lazy()` 配合 `Suspense` 包裹 `Routes`，例如 `const Home = lazy(() => import('./pages/Home'))`；Vite 会为每个 lazy import 自动生成独立 chunk；可给动态 import 加 `/* webpackChunkName: 'dashboard' */` 注释便于调试。
4. 懒加载首屏以下重型组件：对初始不可见的 modal、charts、editor、maps 等组件使用 `lazy` + `Suspense`；例如条件渲染 `{editing && (<Suspense fallback={<EditorSkeleton />}><RichTextEditor /></Suspense>)}`，图表等直接包在 `<Suspense fallback={<ChartSkeleton />}><ChartPanel /></Suspense>` 中。
5. 延迟第三方脚本：不要在 `main.tsx` 顶部同步初始化 Sentry/posthog；改为在 `requestIdleCallback` 或 `setTimeout(..., 2000)` 中动态 `import('@sentry/react')` 和 `import('posthog-js')` 后再初始化；外部 script 标签用 `defer`，或动态创建 `script` 元素、设置 `script.async = true`、`script.src = src` 后 append 到 body。
6. 按用户意图预加载关键资源：在导航链接的 `onMouseEnter` 和 `onFocus` 中触发目标路由的动态 import，例如 `import('./pages/Dashboard')`、`import('./pages/Settings')`；在 HTML head 用 `<link rel="modulepreload" href="/assets/Home-abc123.js" />` 手动预加载关键路由 chunk；Vite 会自动为 entry chunks 添加 modulepreload。
7. 配置依赖预打包：在 `vite.config.ts` 的 `optimizeDeps.include` 中强制预打包 CJS 依赖或深导入，例如 `'react'`、`'react-dom'`、`'react-router-dom'`、`'@tanstack/react-query'`、`'date-fns/format'`、`'date-fns/parseISO'`；在 `optimizeDeps.exclude` 中跳过已是 ESM 或导致问题的依赖，例如 `'@vite-pwa/assets-generator'`；dev 下页面加载慢且请求多时，把未预打包依赖加入 `include`。
8. 启用压缩：在 `vite.config.ts` 引入 `vite-plugin-compression`，在 `plugins` 中分别使用 `viteCompression({ algorithm: 'gzip' })` 和 `viteCompression({ algorithm: 'brotliCompress' })`；生成 `.gz` 和 `.br` 文件；在服务器（Nginx、Cloudflare、Vercel）配置提供这些压缩文件。
9. 定期分析 bundle：每次重大依赖变更后运行 `npx vite-bundle-visualizer`；可在 `package.json` 的 scripts 中加入 `analyze` 命令：`vite build && npx vite-bundle-visualizer`；检查单个 chunk 是否 > 200KB gzipped、多 chunk 是否重复加载库、是否只用了少量函数却加载整库、哪些 `node_modules` 代码可改为动态导入。
10. 用 `import.meta.env` 做死代码消除：用 `if (import.meta.env.DEV) { ... }` 让生产构建移除调试代码；用 `if (import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true') { ... }` 做构建期特性开关；在 `.env.production` 中定义 `VITE_FEATURE_NEW_DASHBOARD=true` 和 `VITE_API_URL=https://api.example.com`。
11. 优化图片与静态资源：在 `vite.config.ts` 的 `build.assetsInlineLimit` 设置为 `4096`，把 <4KB 资源内联为 base64；在 `rollupOptions.output.assetFileNames` 中按扩展名把图片输出到 `images/[name]-[hash][extname]`、字体输出到 `fonts/[name]-[hash][extname]`、其他输出到 `assets/[name]-[hash][extname]`；使用 `vite-plugin-image-optimizer` 并配置 `png: { quality: 80 }`、`jpeg: { quality: 80 }`、`webp: { quality: 80 }`。
12. 配置 dev server proxy：在 `vite.config.ts` 的 `server.proxy` 中把 `/api`、`/auth` 代理到 `http://localhost:3001` 并设置 `changeOrigin: true`；对 WebSocket 的 `/ws` 代理到 `ws://localhost:3001` 并设置 `ws: true`；应用代码使用相对路径如 `fetch('/api/users')`；生产环境在 Nginx 或 Caddy 配置同样的路由。
13. 用 `vite-plugin-pwa` 加 PWA 支持：在 `vite.config.ts` 引入 `VitePWA`；配置 `registerType: 'autoUpdate'` 或 `'prompt'`；设置 `includeAssets: ['favicon.svg', 'robots.txt']`；配置 `manifest` 的 `name`、`short_name`、`theme_color`、`icons`（192x192、512x512）；配置 `workbox.globPatterns` 如 `['**/*.{js,css,html,ico,png,svg,woff2}']`；配置 `runtimeCaching` 对 API 使用 `NetworkFirst`、`cacheName: 'api-cache'`、`expiration: { maxEntries: 50 }`。
14. 选择 CSS 策略：CSS Modules 可直接使用，`import styles from './Button.module.css'` 后写 `className={styles.primary}`；Tailwind CSS 通过 PostCSS 支持，安装 `tailwindcss` 并添加 `postcss.config.js`，配置 `'@tailwindcss/postcss': {}`；优先用 CSS Modules 或 Tailwind，避免 styled-components/Emotion 的运行时开销，如需要 CSS-in-JS 可选 Vanilla Extract 或 Panda CSS 等零运行时方案。
15. 将 React Compiler 配置为 Vite 插件：安装 `npm install -D babel-plugin-react-compiler`；在 `vite.config.ts` 中使用 `react({ babel: { plugins: ['babel-plugin-react-compiler'] } })` 启用；启用后可逐步移除手动 `useMemo`、`useCallback`、`React.memo`；启用后运行测试套件验证行为；要求 React 19；可用 `'use memo'` 指令按文件渐进启用。

适用边界 · 注意事项

• 不适用于非 Vite 或非 React 项目，部分插件和配置依赖 Vite + React 生态。
• 不适用于必须同步初始化第三方脚本、否则核心功能不可用的场景。
• 对非常小的项目，复杂 chunk 拆分、PWA、压缩等优化可能收益有限，需权衡维护成本。