有个项目只用了工具库里的一个防抖函数,构建完之后产物里多出一大坨代码。搜了一下,那个库里的日期处理、深拷贝、字符串模板全在,明明一行都没调用过。

第一反应是「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 背后的构建,骨架都差不多:从入口出发,把每个文件读进来、转换、解析依赖,再顺着依赖继续走,最后把整张图切成几块写出去。

一次生产构建经过的阶段
解析入口把入口路径变成绝对路径,处理别名和扩展名
转换模块TS、JSX、CSS 经过 loader 或插件变成可分析的形式
扩展图从 AST 里读出 import,递归处理每个依赖
切 chunk按入口、共享依赖、动态导入边界分组
生成与压缩输出代码、hash 文件名、sourcemap

这条流水线里有两个词经常被混着用:模块和 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。切分的边界主要有三类:

入口边界每个页面或每个应用入口一个 chunk,天然隔离,互不影响。
共享边界被多个入口引用的模块抽成公共 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 里跑一次真实的生产构建,再拿产物做冒烟测试,别只测开发服务器。

构建时间会随团队规模变成组织问题。 单仓库多包的项目,全量构建动辄十几分钟,靠本地缓存和远程缓存续命。上了缓存之后,又要维护缓存正确性和清理策略。小团队手工管理够用,人一多就得上专门的构建系统,这是成本换来的确定性。

今天就能动手的实验

  1. 用前面那个两模块的小项目,分别在有、无 sideEffects: false 的情况下打包,对比产物体积和内容。
  2. 把 main.js 里的具名导入改成 import * as utils,再打包一次,观察产物还剩多少。
  3. 加一个动态 import(),用静态服务打开页面,在 Network 面板确认请求出现的时间点。
  4. 连续构建两次不改代码,比较所有文件名;再改一个模块,记录哪些文件变了名。
  5. 在构建配置里打开 sourcemap,故意在源码某一行抛错,看浏览器里定位到的是源码还是产物。

小结

打包器是一条流水线:解析入口、转换、顺着 import 建图、切 chunk、生成产物。模块是源码单位,chunk 是产物单位,两者不是一一对应。
分包的三类边界里,只有动态导入是源码显式控制的。路由级拆包优先用它,别把希望全寄托在打包器的启发式规则上。
tree-shaking 只在「静态可分析、无副作用、声明准确」时才生效。体积异常时先查模块格式和副作用,再查配置。
哈希稳定靠稳定的模块 id 和独立的运行时;开发态与产物态往往是两条不同的加载路径,线上问题要拿真实产物复现。

下一篇讲SSR、水合与渲染模式。打包解决的是「代码怎么送到浏览器」,而 SSR 把其中一部分执行挪到了服务端:HTML 先到,JS 后到,中间那段「有内容但不能点」的时间,就是水合要处理的问题。理解了产物的加载时机,再看首屏白屏和 hydration mismatch,会顺很多。