有个项目只用了工具库里的一个防抖函数,构建完之后产物里多出一大坨代码。搜了一下,那个库里的日期处理、深拷贝、字符串模板全在,明明一行都没调用过。
第一反应是「tree-shaking 没开」。查了配置,开着;mode 也是 production。把产物拖进 DevTools 看 sourcemap,发现那堆代码确实来自库的入口文件,而且每个导出都被包进了一个函数,没有一个是能删的。问题不在配置,在库本身:它用 CommonJS 发布,导出是一堆运行时挂到 exports 上的属性,打包器没法在构建阶段确定哪个没被用到。
这类事情会在几个地方反复出现:产物莫名变大、改一行代码缓存全失效、本地开发好好的线上报 process is not defined、动态加载的路由其实首屏就下载了。共同点是,它们都发生在「源码变成产物」这一段。这篇就把这一段拆开,从依赖图一直讲到最终文件。
先复现,再归因
不要拿一个真实的大库当实验对象,变量太多。自己造一个小包,问题会干净很多。
// src/utils/math.js
export function add(a, b) { return a + b; }
export function multiply(a, b) { return a * b; }
// src/utils/index.js ← 桶文件,把所有东西再抛出去
export * from "./math.js";
export * from "./string.js";
// src/main.js
import { add } from "./utils/index.js";
console.log(add(1, 2));
打包:
npx esbuild src/main.js --bundle --minify --outfile=dist/out.js
打开 dist/out.js,搜 multiply 或者 string.js 里的函数名。如果它们还在,说明这次打包没有把没用的导出删掉。接着在 src/utils/package.json 里加一行 "sideEffects": false,重新打包,再看一次。
我的假设是「桶文件 + 副作用标记缺失,导致打包器不敢删」。验证结果通常分两种:加了 sideEffects: false 之后体积明显下降,假设成立;或者一点变化都没有,那就要往下一层查——看看 string.js 顶层是不是有立即执行的语句,或者整个包是不是被打成了 CommonJS。
sideEffects 这个字段,而是理解打包器的判断逻辑:它只会删「确定没用且确定没有副作用」的代码。任何一个条件不满足,它就保守地留下。打包器其实是一条流水线
不管 webpack、Rollup、esbuild 还是 Vite 背后的构建,骨架都差不多:从入口出发,把每个文件读进来、转换、解析依赖,再顺着依赖继续走,最后把整张图切成几块写出去。
这条流水线里有两个词经常被混着用:模块和 chunk。模块是源码层面的一个文件,chunk 是产物层面的一个文件。一个 chunk 里可以塞很多模块,一个模块也可能被拆进不同的 chunk(比如共享依赖)。你看到的 main.js、vendor.js、page-about.js,都是 chunk。
依赖图:节点是模块,边是 import
图里的每个节点是一个模块,每条边是一条 import。构建过程就是不断把新发现的节点加进来,直到没有新的 import 为止。节点里存的东西比你想的多:源码、转换后的代码、解析出的导入导出列表、它依赖谁、谁依赖它。
边不是简单地拿字符串去拼路径,中间有一层解析规则,也是很多「本地能跑、CI 报错」的来源:
- 相对路径和绝对路径怎么换算;
- 省略扩展名时按什么顺序补(
.js、.ts、.jsx); - 别名(
@/)映射到哪个目录,构建工具和编辑器是不是同一份配置; - 包的
exports字段按什么条件选入口:import、require、browser、development。同一个包在 SSR 和浏览器里可能解析成两个不同文件,这就是双格式问题的根源。
构建工具和 TypeScript 各自维护一套解析规则时,编辑器里能跳转、打包时报找不到模块,是很常见的错位。真遇到这种问题,先确认两边用的是不是同一个配置来源,别急着改代码。
图建好之后,打包器还要做一件源码里看不见的事:给每个模块分配一个标识。开发环境常用路径,生产环境常用数字或者哈希。标识稳定与否,直接决定了你改一个文件之后,别的文件会不会跟着变名字——后面讲缓存时会回到这一点。
分包:切在哪儿,决定了用户等多久
最朴素的做法是把整张图打成一个文件。小项目没问题,大项目会有两个毛病:首屏要下载用不到的东西;改一行代码,整个文件的哈希变了,用户缓存全废。
所以要有 chunk。切分的边界主要有三类:
import() 调用处切一刀,只有代码真正执行时才下载。这是唯一由源码显式控制的边界。前两种靠打包器的启发式规则,不同工具的策略不一样,配置项也最容易被复制粘贴。第三种最可靠:你在哪儿写 import(),包就一定在哪儿切开。所以做路由级拆包时,用动态导入比调 splitChunks 参数可控得多。
const routes = [
{ path: "/", load: () => import("./pages/home.js") },
{ path: "/about", load: () => import("./pages/about.js") },
];
代价是加载时机变成运行时的。首屏需要的模块不要动态导入,否则用户会先看到空白再看到内容;反过来,设置页、帮助页这类低频页面,打成独立 chunk 很划算。判断标准是「这个代码在当前页面首次可交互之前,用户有没有可能用到」。
还有一个细节:拆出来的 chunk 之间可能有共享依赖。如果两个异步 chunk 都引用了同一个日期库,打包器要么把它放进公共 chunk,要么复制两份。前者多一次请求,后者多一份体积,没有绝对正确的答案,看你的访问分布。
产物有两种形态
上一篇提到过,打包器要在产物里重建模块系统。重建方式主要有两种,理解它们能解释很多「为什么产物长这样」。
函数包装 + 运行时
每个模块包成一个函数,参数是 module、exports、require。产物里带一小段运行时,负责缓存和按需调用。webpack 是这种思路,兼容性最好,循环依赖也能跑,但产物有一层函数调用开销,体积也大一些。
作用域提升
把能合并的模块直接摊平到同一个作用域,导入导出变成同一个变量的引用,产物里没有模块包装。Rollup 和 esbuild 常用这个思路,产物更小更快,但对循环依赖和副作用边界的判断更保守,拿不准就退回包装。
作用域提升听起来全是好处,其实有个副作用:调试时源码里的模块边界在产物里消失了,一个函数可能来自 A 文件,它引用的变量来自 B 文件,堆栈里看不出分界。这时候只能靠 sourcemap。
tree-shaking 什么时候真的生效
「删掉没用的代码」这件事,打包器靠的是静态分析,不是运行一遍看谁被调用。所以它只在信息足够的时候才敢删。满足下面几条,删除才会发生:
- 模块是 ESM 语法,导入导出写在顶层,名字是静态的;
- 被删的代码没有可观察的副作用,顶层没有发请求、改全局、注册监听之类的语句;
- 包或者项目明确声明了副作用范围(
sideEffects字段,或者构建工具的等价配置); - 没有绕过静态分析的写法,比如
obj[key]动态取属性、export *叠了好几层、把整个命名空间对象传出去。
反过来,下面这些写法会让删除失效,而且往往不报错,只是体积悄悄变大:
| 写法 | 为什么删不掉 | 怎么改 |
|---|---|---|
| CommonJS 库 | 导出是运行时挂到 exports 上的,构建阶段不知道哪些会被用到 | 换 ESM 版本,或者接受整包引入,按需拆成子路径导入 |
桶文件层层 export * | 依赖图被放大,副作用判断变保守,循环依赖风险上升 | 直接从具体文件导入,桶文件只留稳定入口 |
| 顶层有副作用语句 | 删掉可能改变程序行为,打包器不敢动 | 把副作用挪进函数,或者准确声明 sideEffects |
| 整个命名空间被传递 | 无法确定最终用到哪个属性 | 改成具名导入,只传需要的函数 |
| 依赖装饰器元数据 | 类型元数据在运行时被读取,删除会破坏反射 | 确认框架要求,必要时接受这部分体积 |
还有一类容易误判:你只 import 了一个函数,产物里却能看到同文件的其他函数。这不一定是 tree-shaking 失效。如果这些函数被同一个对象字面量或者类引用,它们就是一个整体,删单个函数会破坏结构。判断方法是看 sourcemap 里那部分的归属,而不是凭函数名在产物里搜。
哈希、缓存,以及「改一行全量失效」
生产环境的文件名一般带内容哈希,比如 main.8f3a2c.js。内容变了哈希就变,浏览器自然会重新下载;内容没变,哈希不变,缓存继续生效。听起来很理想,实际常见的问题是「只改了一个页面,怎么所有文件的哈希都变了」。原因通常有三个:
模块标识不稳定。 如果模块 id 是按顺序编号的,中间插一个文件,后面所有模块的编号都往后挪,引用它们的 chunk 内容跟着变。现代打包器默认会用相对路径或者稳定的哈希做 id,但老配置或者手动优化可能把它关掉。
运行时被塞进了业务 chunk。 负责加载其他 chunk 的那段运行时代码里有一张映射表,表里写着每个 chunk 的文件名。任何一个 chunk 改名,这张表就变,装着它的文件也跟着变,进而牵连到引用它的所有入口。把运行时单独抽成一个 chunk,可以把这个连锁反应掐断。
压缩器或者插件输出不稳定。 有些插件在产物里写构建时间、随机 id、绝对路径,内容每次都不同,哈希自然每次都变。用两次构建对比文件名,就能定位到是哪个 chunk 在抖。
开发服务器和生产构建不是同一条路
这件事值得单独说,因为大量「线上才出现」的问题都来自这里。
webpack 的开发服务器仍然是打包:启动时把整张图构建一遍,之后监听文件变化,只重新编译受影响的模块,通过 HMR 把新模块推给浏览器。它的好处是开发和生产用的是同一套模块系统,行为接近;代价是项目一大,启动和热更新都慢。
Vite 的开发模式反过来:不打包,浏览器直接按原生 ESM 请求源码,服务器按需转换单个文件,第三方依赖用 esbuild 预构建成少量文件。所以启动几乎是秒开,改一个文件只重新编译那一个。代价是开发态和产物态的模块系统不同:开发时你调试的是原生 ESM 的顺序,生产时是 Rollup 折叠后的顺序。
HMR 本身也有边界。热更新不是「重新执行整个页面」,而是从改动的模块开始,沿着 import 关系往上传,找到最近一个声明了「我能接受更新」的边界,只替换那一块。找不到边界,就退化成整页刷新。这就是为什么改一个工具函数,有时候页面状态还在,有时候整个表单被清空——取决于它有没有被某个边界接住。
组件框架的 HMR 插件会自动给组件文件加边界,所以改组件通常能保住状态;改一个被很多地方引用的普通模块,往往没有边界,只能整页刷新。
现象、机制、怎么自己验证
| 现象 | 真实机制 | 怎么验证 |
|---|---|---|
| 只 import 一个函数,产物带着整个库 | 库是 CJS、有顶层副作用,或者经过多层桶文件,静态分析不敢删 | 开 sourcemap,在产物里搜同库其他导出名;换成 ESM 子路径导入再对比体积 |
本地开发正常,构建后报 process is not defined |
生产构建替换了环境变量,某个依赖仍在运行时读 process.env |
在产物里搜 process.env,检查 define 配置覆盖了哪些键 |
| 改一个文件,所有 chunk 的哈希都变了 | 模块 id 不稳定,或 chunk 映射表被打进了业务 chunk | 连续构建两次不改代码,看文件名是否一致;再改一个模块,看变化范围 |
| 动态导入的路由,首屏 Network 里就有请求 | 该模块被静态导入链引用,或被配置成预加载,或落进了共享 chunk | 看请求的 initiator,再顺着引用关系找到把静态 import 带进来的那个文件 |
| 压缩后读函数名、类名的地方出错 | 压缩器重命名了标识符,代码却依赖 name 字符串 |
关闭标识符压缩再构建一次,确认问题消失;改成显式传入名字 |
| 开发时样式顺序正常,构建后覆盖关系反了 | CSS 被提取后的顺序由 chunk 图和依赖顺序决定,不是源码书写顺序 | 对比两次构建的样式表顺序,检查是否依赖了隐式的导入顺序 |
| sourcemap 指向的行号和源码对不上 | 多层 loader 转换叠加,或者 sourcemap 没有逐层传递 | 在 Sources 面板打开原始文件,确认映射;检查每个 loader 是否都输出了 map |
边界与代价
tree-shaking 有天花板。 动态属性访问、反射、装饰器元数据、CJS 互操作,都会让它退化成保守删除。追求极致体积就要改写法,改写法又会降低代码的可读性和兼容性。这笔账要按项目实际情况算,不是越小越好。
分包过度也是一种浪费。 每个 chunk 都是一次请求,带自己的协议开销和解析成本。把页面拆成二十个小文件,在弱网下可能比一个大文件更慢,因为请求要排队。合理的做法是先按路由切,再根据实际访问数据调整,不要凭感觉切得很碎。
构建缓存能省时间,也能制造幻觉。 缓存命中时构建很快,但缓存键漏了某个输入(环境变量、配置文件、生成代码),就会拿到过期产物。规则是:凡是影响输出的东西,都要能被缓存系统看到。
压缩和混淆会牺牲可调试性。 生产环境不开 sourcemap,线上报错只有一串压缩后的位置,排查全靠猜;开了 sourcemap,又要考虑源码泄漏和体积。常见折中是生成但不公开,只上传给错误监控平台。
dev 与 prod 的差异是持续的 bug 来源。 环境变量、压缩、CSS 顺序、模块执行顺序、React 的开发检查,任何一项都可能只在其中一边出现。能做的是在 CI 里跑一次真实的生产构建,再拿产物做冒烟测试,别只测开发服务器。
构建时间会随团队规模变成组织问题。 单仓库多包的项目,全量构建动辄十几分钟,靠本地缓存和远程缓存续命。上了缓存之后,又要维护缓存正确性和清理策略。小团队手工管理够用,人一多就得上专门的构建系统,这是成本换来的确定性。
今天就能动手的实验
- 用前面那个两模块的小项目,分别在有、无
sideEffects: false的情况下打包,对比产物体积和内容。 - 把
main.js里的具名导入改成import * as utils,再打包一次,观察产物还剩多少。 - 加一个动态
import(),用静态服务打开页面,在 Network 面板确认请求出现的时间点。 - 连续构建两次不改代码,比较所有文件名;再改一个模块,记录哪些文件变了名。
- 在构建配置里打开 sourcemap,故意在源码某一行抛错,看浏览器里定位到的是源码还是产物。
小结
下一篇讲SSR、水合与渲染模式。打包解决的是「代码怎么送到浏览器」,而 SSR 把其中一部分执行挪到了服务端:HTML 先到,JS 后到,中间那段「有内容但不能点」的时间,就是水合要处理的问题。理解了产物的加载时机,再看首屏白屏和 hydration mismatch,会顺很多。