Vite生产环境代码分割与懒加载优化：从首屏提速到缓存策略

如果你用 Vite 做过生产环境部署，大概率经历过这种情况：开发环境里页面秒开，热更新快得飞起，npm run build也很顺畅，但产物一上线，浏览器里白屏时间肉眼可见地变长。这不是玄学，而是开发模式和生产构建的运行机制完全不同。今天这篇就围绕 Vite 生产环境下的代码分割与懒加载优化，把我实际调过的一整套方案、踩过的坑一次性说清楚。适合那些项目已经跑起来、但首屏性能不太满意的 Vite 使用者，尤其是用 React 或 Vue 建了中后台、门户这类带路由和大量页面场景的同学。

1. 为什么要做代码分割：先理解 Vite 生产构建的“打包逻辑”

1.1 开发模式快，不代表生产构建快

Vite 开发模式之所以快，是因为它压根不做打包。开发服务器按需把模块转成浏览器能直接识别的 ES Module，谁被访问到就实时编译谁。页面打开时，浏览器通过import语句自己会去拉对应的模块文件，天然就是“按需加载”。这也是 Vite 名字的由来——法语里就是“快”的意思，核心卖点在开发体验。

生产构建就完全换了一套逻辑。Vite 内置的 Rollup 要把成百上千个模块拍扁，合并成少数几个静态文件。Rollup 默认的策略是：业务代码打成一个文件，node_modules里被引用的第三方代码打成一个 vendor 文件。也就是说，哪怕你的项目只有一个入口页面里放了一份智能报表，只要这个报表组件在路由表里被静态import了，它就会和整个业务代码一起进入同一个 chunk。所有页面的代码、所有被引用的图形库、UI 组件库，全部挤在一个文件里。项目越大，这个文件越大，首屏白屏就越难避免。

这里用一个生活类比：开发模式像去超市买东西，需要什么才伸手拿什么；生产模式则像搬家，把所有东西塞进同一只大纸箱，不管你现在只缺一把螺丝刀。Rollup 不知道用户什么时候会用到哪块代码，它只能尽量保证“全都有”，而代码分割要解决的，恰恰是“用户此刻真正需要什么”。

1.2 全量打包的代价到底有多大

拿我优化过的一个中后台项目举例，技术栈是 React + Ant Design + ECharts。刚接手时没有任何分割和懒加载，构建产物里有个 main.js，gzip 后体积大约 480KB。看着好像还能接受，但浏览器对 JS 的消耗远不止下载那一下，还有解析、编译、执行。一个 500KB gzip 的 JS，在普通 4G 网络和低端安卓机上，从请求到可交互，实测起步就是 3 秒以上。用户打开登录页，结果把整个后台所有页面的代码都下载下来了，这就是典型的“首屏为全站买单”。

如果你做的是多页面应用或带权限路由的大型系统，这个浪费更夸张。某个只在小范围使用的数据大屏页面，如果被静态引入，它的初始化逻辑、图表库、地图组件，全都会成为首屏的一部分。代码分割与懒加载的核心目标只有一个：按需让用户当前要用的代码先到，其余代码等用户真的会用到时再接。

这一节同时想说明一个容易被忽略的点。代码分割不是 Vite 的“可选增强功能”，而是生产环境构建绕不开的基础操作。它跟性能优化不是一个层面的东西，更像是“你既然用了构建工具，就应该把产物组织好”的基本功课。理解了为什么，下一步看怎么做。

2. 懒加载优先：用动态 import() 撬动首屏体积

2.1 动态 import() 是懒加载的底层基础

代码分割最直接的触发方式，就是把静态import改成动态import()。Rollup 遇到import()调用时，不会把它合并进主包，而是把该模块及其依赖单独拆成一个 chunk，这个 chunk 只有在运行时import()被执行的时候才会真正加载。

需要注意的是，这里的import()是发生在浏览器端的，底层是动态创建 script 标签去拉取对应的 JS 文件，返回一个 Promise。所以你可以配合 async/await 使用，也可以直接把它交给 React.lazy、Vue 的 defineAsyncComponent 这类框架封装。

// 静态导入：模块在首屏 bundle 里 import { renderChart } from '@/utils/chart' // 动态导入：模块被拆成独立 chunk，用到才加载 const { renderChart } = await import('@/utils/chart')

动态import()本身不需要额外配置，能立刻让产物发生变化。但有一个硬性约束：传递给import()的路径必须在静态分析时能解析。也就是说，路径里不能是纯运行时拼出来的变量，否则 Rollup 无法打包。像const path = someFlag ? 'a.js' : 'b.js'; import(path)这种写法，构建会直接失败或产生奇怪的产物。正确做法是路径前缀固定、只把文件名后缀通过变量拼接，让 Rollup 能枚举出所有可能的 chunk。

2.2 路由懒加载：最简单也最有效的第一刀

对一个带路由的前端应用来说，路由懒加载是投入产出比最高的一步。绝大多数业务系统，用户访问一个工作台页面时，根本不会用到用户管理、系统配置这些页面里的代码。把这些页面从首屏里摘出去，效果是立竿见影的。

React Router 6 的写法，配合 lazy 和 Suspense：

import { Suspense, lazy } from 'react' import { createBrowserRouter } from 'react-router-dom' const Dashboard = lazy(() => import('@/pages/Dashboard')) const UserManage = lazy(() => import('@/pages/UserManage')) const SysConfig = lazy(() => import('@/pages/SysConfig')) const router = createBrowserRouter([ { path: '/', element: <Layout />, children: [ { path: 'dashboard', element: ( <Suspense fallback={<div style={{ padding: 24 }}>页面加载中...</div>}> <Dashboard /> </Suspense> ) }, { path: 'user', element: ( <Suspense fallback={<div style={{ padding: 24 }}>页面加载中...</div>}> <UserManage /> </Suspense> ) } ] } ])

Suspense 的 fallback 是必须的，因为异步组件加载期间，React 需要一个占位内容。我建议 fallback 不要只放一句“加载中”，最好配合 UI 组件库的 Spin、Skeleton，或者自定义一个简单的骨架屏。用户体验的差别非常大——哪怕代码只加载 100ms，白一下屏都比“正在加载”的感觉差。

Vue Router 更简洁，component 直接写成返回 Promise 的函数即可：

const routes = [ { path: '/dashboard', name: 'Dashboard', component: () => import('@/views/Dashboard.vue') }, { path: '/user', name: 'UserManage', component: () => import('@/views/UserManage.vue') } ]

Vue Router 内置了对异步组件的支持，写在 component 位置的动态 import 函数会自动处理好。关键是别把所有路由一次性全改成懒加载就完事，还要注意少数“登录后必到”的页面，比如工作台、首页，可以保持静态导入或提前预加载，避免它们在每次首次访问时都有一次额外的网络往返。我实际操作中发现，把首页也懒加载，首屏指标没改善多少，反而多了一次加载过程，后来干脆恢复成静态导入。

2.3 组件级懒加载：React 和 Vue 的落地写法

路由懒加载解决的是页面级的拆分，但有些页面上会带很重的局部模块，比如 PDF 预览、富文本编辑器、可视化大屏、代码高亮这类组件。它们不在首屏必然出现，只有用户点了某个按钮或满足某个条件后才会渲染。这种情况属于组件级懒加载。

React 里用 React.lazy 包裹目标组件，再用 Suspense 包一层：

import { lazy, Suspense, useState } from 'react' const PdfPreview = lazy(() => import('@/components/PdfPreview')) const RichEditor = lazy(() => import('@/components/RichEditor')) function DocDetail({ fileUrl }) { const [showPreview, setShowPreview] = useState(false) return ( <div> <button onClick={() => setShowPreview(true)}>预览文档</button> {showPreview && ( <Suspense fallback={<div>文档解析中...</div>}> <PdfPreview url={fileUrl} /> </Suspense> )} </div> ) }

注意 React.lazy 要求子组件必须是默认导出，这是新手很容易踩的雷。如果组件是export function这种命名导出，就得在动态 import 里转一下：lazy(() => import('@/components/PdfPreview').then(m => ({ default: m.PdfPreview })))。

Vue 侧可以使用 defineAsyncComponent：

import { defineAsyncComponent } from 'vue' const PdfPreview = defineAsyncComponent({ loader: () => import('@/components/PdfPreview.vue'), loadingComponent: Loading, errorComponent: LoadError, delay: 200 // 延迟显示 loading，避免快速加载时闪烁 })

defineAsyncComponent 比 React.lazy 的封装更贴近业务：你可以单独指定加载中的组件、失败时的组件、超时时间。delay 参数值得注意——如果组件 100ms 就加载完了，就不用让 loading 组件闪现出来，先等 200ms 再决定是否显示 loading，体验会自然很多。

组件级懒加载做完后，工具类模块也别放过。比如一个项目里封装了导出表格、下载文件、压缩图片的 util，它们很可能在某个详情页才用到。把这些 util 改成按需动态导入，收益虽然不如大组件那么明显，但累积起来也很可观。关键是养成习惯：只要一个模块不是入口页必须用的，就考虑拆出去。

3. manualChunks 精细分组：让第三方库各归各位

3.1 为什么 Vite 默认的第三方库分包还不够

动态import()解决了“业务代码按路由拆”的问题，但还有个漏网之鱼：一个大页面引了 ECharts，另一个页面引了 Ant Design，Rollup 默认会把所有node_modules的第三方代码打成一个大的 vendor chunk。这个 vendor 可能几百 KB，而且只要任何一个页面用到了它，它就会跟着某个 chunk 被一起加载——因为它是被多个模块间接依赖的公共依赖。

另一个更现实的痛点跟缓存策略有关。如果所有第三方代码都在同一个 vendor 文件里，那么只要其中一个依赖升级了，整个 vendor 的 hash 就会变，用户客户端缓存里的旧文件全部失效。这等于一次低频改动牵连了所有第三方的缓存。

manualChunks 就是为了解决这类问题而存在的。它让你手动指定哪些模块进入哪些 chunk。最典型的分组思路是：React 全家桶一组、UI 组件库一组、图表库一组、剩余第三方库兜底一组。

3.2 两种配置方式：对象形式与函数形式

对象形式最简单，直接把包名列进去：

// vite.config.js import { defineConfig } from 'vite' export default defineConfig({ build: { rollupOptions: { output: { manualChunks: { 'react-vendor': ['react', 'react-dom', 'react-router-dom'], 'ui-vendor': ['antd', '@ant-design/icons'], 'chart-vendor': ['echarts'] } } } } })

它的缺点是只对“直接以包名形式出现在 node_modules”的模块生效。很多 UI 组件库内部还会间接依赖几十个小包，比如 dayjs、rc-* 系列。你只把 antd 放进去，那些间接依赖可能还是会被扔到别的 chunk 里，或者因为被多个分组依赖，被 Rollup 单独再分一个共享块。

函数形式更灵活，能看到每个模块的完整路径，适合做兜底：

manualChunks(id) { if (!id.includes('node_modules')) return if (id.includes('echarts') || id.includes('zrender')) { return 'chart-vendor' } if (id.includes('antd') || id.includes('@ant-design')) { return 'ui-vendor' } if (id.includes('react') || id.includes('react-dom') || id.includes('react-router')) { return 'react-vendor' } return 'vendor' }

函数形式的核心规则是：返回字符串表示模块归入该组，返回 undefined 表示交给 Rollup 默认逻辑处理。我最开始写的时候踩过一个坑——同一模块可能匹配到多个 if 分支，比如某个 antd 组件内部依赖了 react，按上面顺序走就还好，但如果我先把 react 的判断放在前，那么 antd 代码里凡是 import 了 react 内部方法的模块都会被塞进 react-vendor，出现 chunk 之间交叉引用。所以判断顺序很关键，大范围的、通用性的判断放在后面，具体的包判断放在前面。

3.3 拆分粒度怎么定：不是越细越好

有些同学看完手册，恨不得把每个 npm 包都拆成一个 chunk，这种思路在极端情况下反而是反效果。每个 chunk 都是一个独立的网络请求，HTTP/1.1 下浏览器并发请求数有限制，HTTP/2 虽然有连接复用，但大量小文件也会带来额外的解析开销和缓存碎片。

我现在的默认做法是控制在 3-5 个第三方 chunk。框架一组，UI 组件库一组，图表或富文本这类体量大的专门一组，剩下的兜底成一组。这样部署时，任何一组升级只会影响该组的 hash，业务代码和其余第三方库的缓存都能保住。

还有一个细节：manualChunks 的配置要和路由懒加载结合着看。业务代码里的公共依赖如果被很多懒加载 chunk 共享，Rollup 会自动提取 shared chunk。这个行为一般不用干预，但如果你发现某个被大量页面用到的工具函数被打进了每个人各自的 chunk，导致重复代码膨胀，可以考虑把那个工具模块在 manualChunks 对象里也指定为一个分组，强制它成为一个独立的公共块。

4. 用构建分析工具验证优化效果

4.1 安装和使用 vite-plugin-visualizer

做任何优化之前，先看看产物现状。我推荐 vite-plugin-visualizer，它是构建后自动生成 HTML 分析报告的工具，能直观展示每个 chunk 的体积和模块构成。

npm i -D vite-plugin-visualizer

然后在 vite.config.js 里挂上插件：

import { defineConfig } from 'vite' import { visualizer } from 'vite-plugin-visualizer' export default defineConfig({ plugins: [ visualizer({ open: true, gzipSize: true, filename: 'analyze.html' }) ] })

配置里的 open 会在构建完成后自动打开浏览器，gzipSize 会在报告里显示 gzip 压缩后的体积。跑一次npm run build，dist 目录下会多出一个 analyze.html，也会自动弹窗展示。这个文件记得在部署时从静态资源目录里排除掉，别让它被用户访问到。

4.2 读懂分析报告的几个关键视角

报告打开后，第一眼先找“大块头”。一个几百 KB 的 chunk 多半是问题所在。我一般按三个视角确认：

• 入口 chunk 里有没有不该出现的页面级代码
• 图表、UI 组件库是否被正确拆到了独立 chunk
• 是否存在体积异常但从不被直接访问的孤儿 chunk

拿我之前优化的项目举例，优化前后对比大致是这样：

入口从 480KB 掉到 38KB，用户打开系统时的网络耗时和解析耗时都大幅下降。UI 库和图表库虽然总体积没变，但变成了用户访问对应页面时才加载，场景匹配度一下子就对了。

分析工具只是眼睛，真正下手时要按“业务页面 > 第三方库 > 工具模块”的优先级调整。不要一开始就疯狂拆 vendor，先看哪个 chunk 最大、哪个 chunk 的加载时机和用户访问路径不匹配，然后有针对性地改。

5. 常见问题与排查技巧实录

5.1 动态导入路径报错

动态 import 的路径里放纯变量会报错或导致产物不正确。要写成可枚举路径：

// 错误做法：纯变量路径无法静态分析 const page = someFlag ? 'Home' : 'List' const mod = await import(`@/pages/${page}.js`) // 可枚举做法：Rollup 可以完整解析每个分支 const mods = { Home: () => import('@/pages/Home.js'), List: () => import('@/pages/List.js') } const mod = await mods[page]()

如果构建报错信息里出现 “Cannot analyze dynamically imported path” 或类似字眼，基本就是这个问题。解决思路就是让 import 的参数在构建时是确定的，哪怕只是“前缀 + 有限枚举的变量”也可以。

5.2 manualChunks 配置后出现循环依赖警告

Rollup 提示 “Circular dependency” 或 chunk 之间相互引用时，多半是 manualChunks 函数给同一模块分到了多个组，或者两个分组之间存在交叉依赖。比如 antd 分组和 react 分组互相引用了对方的模块。解决思路：保证每个模块只能归属一个 chunk；函数返回 undefined 时让 Rollup 自行处理。如果某个第三方包被拆进两个 chunk，可以考虑把它们的公共依赖单独提一层，或者干脆把这两个分组合并成一个。

5.3 懒加载组件首次渲染白屏闪烁

问题常出在 Suspense 的 fallback 没配合 loading 组件，或 delay 没调好。React 这边就是直接加 fallback 骨架屏；Vue 用 defineAsyncComponent 的 delay 控制，建议 200-300ms 起步。另外检查浏览器 DevTools 的 Network 面板，确认按需下载的 chunk 是否真的在点击后触发，如果没有触发，可能组件被意外静态引入而非懒加载。

5.4 部署时的缓存策略配合

生产构建后 dist 里带 hash 的文件名（比如 main-6a918b.js）就是为了长缓存。nginx 里可以对 /assets/ 开启一年不可变缓存，index.html 禁止缓存：

location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; } location / { try_files $uri $uri/ /index.html; add_header Cache-Control "no-cache"; }

懒加载的 chunk 同样在 /assets/ 下，缓存策略一样适用。很多云托管平台默认对 HTML 和静态资源一视同仁，这会导致 hash 变更后用户拿到旧的 index.html，找不到新版本的 chunk 路径。遇到部署后用户反馈白屏或 404，优先排查的就是 HTML 是否被缓存。

5.5 一个小技巧：入口 chunk 的 preload 安排

如果首屏登录页依赖的公共代码不多，又不敢把所有页面全部动态化，可以考虑在 index.html 里给关键 chunk 加 preload。Vite 默认会对入口 chunk 自动注入预加载标签，手动添加时留意别重复。preload 的核心作用是提前告知浏览器去下载后续可能会用到的资源，但加多了反而浪费带宽，只挑 2-3 个高概率用到的 chunk 即可。

我个人的实际操作体会是，做代码分割和懒加载优化，不需要一次把方案做到“完美”。我一般按这个顺序推进：先用分析工具扫一遍产物，确认最大 chunk 是谁；然后把路由改成懒加载，立刻对比构建产物体积；再按第三方库的实际情况配置 manualChunks；最后补组件级懒加载和缓存策略。很多项目做到第二步就已经能省掉一半以上的首屏体积了。有一个印象深刻的案例是某跨平台系统的图表部分，只做了一个手动拆分，首屏 gzip 体积从 420KB 掉到 115KB，后续再优化就是锦上添花了。代码分割不是越炫越好，而是让用户真正需要的那部分代码先到、其余代码乖乖待命。