有个项目,首屏包 3.2MB,压缩后 1.1MB,产品经理天天在群里问「为什么打开这么慢」。我们当时的反应很标准:拆包。路由级动态导入、vendor 手动分组、再加一点预加载,一套操作下来,chunk 从 1 个变成 42 个。然后首屏从 4.1 秒变成了 5.8 秒。
那次的教训是:拆包不等于变快。拆包只是把「一次下载一大堆」改成「按需下载几小堆」,如果拆出来的东西仍然要全部加载,只是多付了 41 次请求的组织成本,那就纯亏。摇树(tree shaking)也一样,它不是构建工具的一个开关,而是「代码有没有写成可分析的形式」的结果,前提条件不满足,打开开关也只是白开。
这篇把这两件事分开讲:拆包决定「什么时候下、下多少」,摇树决定「哪些代码根本不进产物」。它们的目标不同,失败时的症状也不同,混在一起调只会越调越乱。
先分清两个数字:传输体积与执行成本
「包太大」这句话至少包含三个不同的成本,优化手段也不一样。
下载成本:用户要等的字节数,跟网络相关。压缩(gzip / brotli)、砍依赖、按需加载都作用在这里。1MB 的 JS 在 4G 网络下大约要 2 到 4 秒,在弱网下能到十几秒。
解析与执行成本:浏览器拿到 JS 之后要解析、编译、执行。这部分跟 CPU 相关,中低端安卓机上,1MB 未压缩的 JS 解析加执行可以到 1 秒以上,而且发生在主线程,直接顶住首屏渲染。压缩传输省不了这部分,只有减少代码量才行。
调度成本:请求数、依赖链长度、缓存命中率。拆包主要影响这一项。拆得太粗,首屏背了一堆用不到的东西;拆得太细,请求瀑布和缓存碎片又来了。
所以「拆包」这个动作,真正能改善的是第三段,顺带改善第一段(少下没用的)。它对第二段几乎无效:代码总量没变,只是分开放了。很多团队把这三段混着说,于是得出「拆了包就该变快」的错误预期。
那次拆包为什么反而更慢
复盘下来有四个原因,每一个单看都不致命,叠在一起就把收益吃光了。
第一,拆出来的 chunk 首屏全都要。路由级拆分没错,但我们把「所有路由共用的东西」——国际化的语言包、权限配置、全局字典、图表库——都放进了首屏入口。等于把一个大包切成「一个大包加四十个小包」,小包里塞的还是原来那些东西,只是多了请求。
第二,请求瀑布。入口 chunk 里先动态导入 A,A 执行时才知道要导入 B,B 又要 C。每一层都要等一个完整的往返,4G 下 RTT 大约 100 到 200 毫秒,四层就是半秒以上。原来一个大包虽然大,但只有一个往返。
第三,缓存全失效。我们把 vendor 按库拆成十几个 chunk,任何一次依赖升级都会改掉所有 chunk 的 hash。用户每次发版后都要重新下几乎全部代码,之前「拆细了好缓存」的假设完全没成立。真正该稳定的是「不常变的那一大块」,而不是「每个库一小块」。
第四,预加载太贪心。为了掩盖瀑布,我们给所有 chunk 加了 modulepreload,等于告诉浏览器「这些都可能用到,先下吧」。带宽被四十个请求平分,首屏那几个真正关键的反而不先到。预加载应该只给「下一步一定会用到」的一两个资源。
重新做一遍:约束、方案和取舍
第二次改之前,我们先把约束写清楚,不然后面又会凭感觉调。
| 约束 | 实际情况 | 对方案的影响 |
|---|---|---|
| 用户网络 | 三成用户 4G,两成在弱网或地铁环境 | 首屏关键路径请求数必须压到个位数 |
| 发布频率 | 每天 8–12 次,随时可能回滚 | chunk hash 必须可预期,旧版本产物要保留 |
| 技术栈 | 新应用 Vite 5 + Rollup 4,老应用 webpack 5 | 两套拆包配置,概念要对齐 |
| 依赖 | ECharts 全量、lodash 全量、一个内部 UI 库 | 摇树和按需引入是主要收益来源 |
| 团队 | 20 人,构建配置只有两人熟 | 规则要少、要能被工具自动检查 |
方案层面比较了三种,最后选的不是最激进的那种。
A. 全面细拆:每个路由、每个库都单独成 chunk
理论上缓存最优,实际会得到几十个请求和一条深的依赖链。首屏关键路径被拉长,弱网下体验最差。适合访问路径分散、单页停留时间长的后台系统,不适合首屏就要完整的 C 端页面。
B. 只拆路由,其余全进一个 vendor
实现简单,请求数可控。问题是 vendor 会随着业务代码一起膨胀,最后回到「一个巨大的首屏包」。而且所有不常变的依赖和常变的业务代码混在一个 hash 里,缓存命中率一般。
C. 三层结构:首屏关键、稳定依赖、按需路由
首屏只保留真正渲染第一屏所需的代码;框架和体积大且稳定的依赖单独一块,hash 尽量稳;其余路由和重型组件按需加载,并对「下一步必用」的一两个做预加载。这是我们最后选的。
D. 不拆,改用更狠的压缩和 CDN
brotli 能把文本再压 15% 到 20%,CDN 能缩短 RTT,但都动不了「代码量」和「执行成本」。在老网络环境或者内网部署里,CDN 还不一定可用。可以作为配套手段,不能当主方案。
三层结构的核心判断是:只有「首屏渲染必须执行到的代码」才配进关键路径。判断方法很土但有效——把首屏渲染的调用栈打出来,看实际执行了哪些模块,剩下的全都可以推迟。我们第一次就是没做这个,凭「这个库很重要」的印象往首屏塞。
// 路由级按需加载:注释写清「为什么要拆」,否则半年后没人敢动
const routes = [
{ path: "/", component: () => import("./pages/home.js") },
{ path: "/report", component: () => import("./pages/report.js") },
// 重型图表只在报表页用,不随首屏下载
{ path: "/analysis", component: () => import("./pages/analysis.js") }
];
// 预加载只给「点进来大概率下一步就用」的资源
function prefetchReport() {
import("./pages/report.js");
}
document.querySelector("#nav-report")
?.addEventListener("mouseenter", prefetchReport, { once: true });
import("./pages/" + name + ".js") 这种写法,Rollup 和 webpack 都无法静态分析,只能把整个目录打进产物,拆包等于没做。确实需要按名字加载时,写一张显式的映射表,让工具能看见所有可能的目标。摇树:为什么你的代码摇不掉
摇树的原理不复杂:构建工具从入口出发,沿着 import/export 建立模块图,标记哪些导出真的被用到,剩下的在生成阶段删掉。它能成立需要三个条件,缺一个就会退化成「原样打包」。
条件一:模块必须是 ESM。CommonJS 的 module.exports 是运行时对象,属性可以动态赋值、可以被外部改写,工具不敢删。一个库如果只提供 CJS 入口,你怎么配都摇不动。lodash 的经典问题就在这:lodash 是 CJS,lodash-es 才是 ESM,两个包内容一样,产物能差出几百 KB。
条件二:模块要声明自己没有副作用。工具默认认为「导入一个模块可能产生副作用」,比如修改全局变量、注入 CSS、注册 polyfill。如果库的 package.json 里写了 "sideEffects": false,工具才敢在「没用到任何导出」时整块删掉。写错了会删掉真正有副作用的代码,症状是「某个功能悄悄没了」。
条件三:调用要能被静态判断。顶层立即执行、动态属性访问、把整个命名空间传出去,都会让工具放弃。比如 import * as utils from "./utils"; Object.keys(utils).forEach(...),工具无法知道你用了哪几个,只能全留。
// package.json(库作者视角)
{
"name": "my-lib",
"module": "dist/index.mjs",
"main": "dist/index.cjs",
"sideEffects": ["*.css", "./src/polyfill.ts"]
}
注意 sideEffects 写成数组而不是 false,因为 CSS 导入和 polyfill 确实有副作用。很多人图省事写 false,然后发现样式全丢了,回头把整个摇树关掉——这是最常见的倒退路径。
还有一个常被忽略的点:转译目标会影响摇树质量。如果 Babel 或 esbuild 把 class 降级成函数、把常量折叠掉,静态结构会被破坏,工具能分析的信息变少。现代浏览器项目把 target 设到 ES2020 之后,产物反而更小、更好摇。为了兼容早已不支持的浏览器把代码降到 ES5,是体积和性能的双重损失。
即使库本身是可摇的,引入方式也会决定结果。以 lodash 为例,import _ from "lodash" 会把整个库拉进来;import { debounce } from "lodash-es" 只留一个函数;而 import * as _ from "lodash-es" 又会让工具无法判断你用了哪些属性,退回全量。这三种写法在代码 review 里看起来差不多,产物可能差几百 KB。我们的做法是在 ESLint 里直接禁止前两种写法,让问题在写代码时就暴露,而不是等到分析产物。
另一个常见误区是「按需引入的插件一定生效」。很多组件库提供 babel-plugin-import 这类插件,原理是在编译时把桶导入改写成深层路径导入。它只对「具名导入」有效,如果你写了 import * as UI from "ui-lib" 再动态取属性,插件不会改写,摇树也救不了。换库、换插件之前,先用产物分析确认改写真的发生了。
CSS 的「摇树」要单独说。CSS 没有导入导出语义,工具只能按「这个选择器是否在 HTML/JS 里出现过」来猜,猜错的代价是样式丢失。所以 CSS 的裁剪通常放在运行时或独立工具里做,不要指望构建阶段的 JS 摇树顺手解决。
拆完之后真正踩的坑
第二次上线后首屏从 5.8 秒回到 3.4 秒,但没有一步到位。下面这些现象是接下来两个月陆续遇到的,基本覆盖了拆包和摇树的常见故障面。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 拆完首屏反而更慢 | 关键路径变成串行请求瀑布,或拆出的 chunk 首屏全都要 | 网络面板看首屏关键请求的时序与深度;对照 LCP 元素依赖的资源 |
| 体积几乎没降 | 依赖是 CJS 入口,或库没标 sideEffects | 产物分析器里搜模块名;看该库 package.json 的 module 字段 |
| 同一个库在多个 chunk 里重复出现 | 分组规则重叠,或动态导入与静态导入混用同一模块 | 构建分析报告里的重复模块列表 |
| 发版后部分用户白屏,报 ChunkLoadError | 旧 chunk 被部署覆盖,还停留在旧页面的用户加载不到 | 发布目录是否保留上一版本;错误监控里该错误的量级 |
| 页面一次加载四十多个 JS | 拆得过细,或预加载把全部 chunk 都列上了 | 数一下首屏实际请求数与 preload 标签数 |
| 摇树开启后某个功能失效 | 有副作用的模块被标成了 sideEffects: false | 对比关闭摇树的产物行为;检查库的 sideEffects 配置 |
| 首屏 preload 了却没用上 | 预加载按「可能会用」而不是「一定会用」来配 | 把 preload 列表和实际请求列表做差集 |
| 打包时间从 40 秒涨到 4 分钟 | chunk 数量过多,或拆包规则导致重复分析 | 构建日志里各阶段耗时;chunk 总数 |
ChunkLoadError 值得单独讲,因为它是拆包引入的、最像「线上事故」的一类问题。用户打开页面后没有刷新,半小时后点击某个按钮,此时新版本已发布,旧的 chunk 文件被删除,动态导入 404。用户在同一个页面里,代码却已经过期。解决办法有两层:部署时保留上一版本的产物至少一个发布周期;应用层监听这个错误,提示刷新或自动重载一次。第二层要有防循环的保护,不然用户会陷入反复刷新。
边界与代价:拆到什么时候该停
拆包和摇树都有收益递减,而且都有实打实的成本。几条经验线:
总量小于 200KB(压缩后)的站点,别拆。一个请求的往返成本,可能比省下的字节更贵。尤其是内网、局域网部署,RTT 很低,拆开只有坏处。
首屏关键路径请求超过 10 个,说明拆过头了。浏览器对同一域名的并发连接有限,多出来的请求要排队。这时候应该合并,而不是继续优化预加载。
只有一两个人在维护构建配置时,不要上太细的手工分组。规则越细,越依赖某个人的记忆。半年后他调岗,没人敢改 manualChunks,构建就冻结了。能用自动分组解决的问题,不要手工切。
摇树的收益取决于依赖质量,不取决于配置。如果主要体积来自几个 CJS 老库,正确做法是换库或按需引入,而不是在构建配置里加一堆 usedExports、providedExports 之类的开关。那些开关只对本来就能摇的代码有效。
缓存粒度比拆包粒度更重要。很多团队把精力花在「怎么切得更细」,却忽略了「切出来的文件 hash 会不会跟着无关改动一起变」。判断方法很简单:连续发两次只有业务文案变化的版本,看用户重新下载了多少字节。如果每次都接近全量,说明分组策略有问题,拆得再细也没用。
还有一个隐性代价:拆包让「代码在哪」变得不直观。排查线上问题时,报错堆栈指向一个叫 chunk-7f3a.js 的文件,你得先有 sourcemap 才能定位。sourcemap 要不要上传、上传到哪、要不要公开,又是另一套工程问题,后面讲监控时会展开。
今天就能动手的五件事
一、先画产物,不动配置。Vite 用 rollup-plugin-visualizer,webpack 用 bundle-analyzer,生成一份 treemap。先回答一个问题:体积最大的三个模块是什么?通常答案会让你意外,比如某个只在设置页用的富文本编辑器。
二、对照首屏实际执行。在首屏渲染完成后打一个断点或性能标记,看调用栈里出现了哪些模块。把它们和产物报告对照,凡是「首屏没执行」的,都可以考虑推迟加载。
三、做一次摇树对照实验。写一个只用到某库一个函数的文件,分别用 ESM 入口和 CJS 入口打包,比较产物大小。这个实验十分钟能做完,但能让你以后判断「这个库能不能摇」不再靠猜。
四、在弱网和慢 CPU 下测。Chrome 开发者工具把网络设成 Fast 4G、CPU 降速 6 倍,分别测拆包前后的 LCP 和首次可交互。桌面宽带下测出来的数字,几乎一定会骗你。
五、模拟一次 ChunkLoadError。发版后手动删掉旧 chunk,或者直接访问一个不存在的 chunk 地址,看应用是白屏、报错,还是有兜底。没有兜底的话,这就是下一次线上的事故形态。
小结
拆包解决的是加载顺序和缓存粒度,摇树解决的是死代码,两者不能互相替代。判断拆得好不好,看的是首屏关键路径的请求数与深度;判断摇得好不好,看的是产物里还有没有「整包引入」的依赖。
但这两件事都有一个共同的前提:你得能证明改动真的有效。我们第一次拆包之所以错得那么彻底,是因为从头到尾没有测过弱网下的真实指标,全凭「包变小了应该更快」的直觉。下一篇讲性能工程,就是把这套「先量化、再改、再验证」的闭环搭起来。