只 import 一个函数,整包还是进来了:sideEffects 到底承诺了什么

Tree Shaking 是打包器沿着 ESM 的静态导入图,把从入口不可达的导出和模块删掉;sideEffects 则是 package.json 里由作者签下的一张声明,说明这个包里的模块在被 import 求值时会不会改动外部世界。打包器无法证明顶层代码无害,默认只能保守保留,所以决定整包去留的往往不是代码写得多干净,而是这张声明准不准。最常见的误区是把 sideEffects 设为 false 当成性能开关,以为它能删掉模块里的某条语句,或者只测开发环境就宣布优化生效。读完你能分清导出级、模块级、语句级三层删除,知道 CSS、polyfill 与 barrel 文件为什么会在这件事上翻车,也能给库作者和使用方各列出一份可执行的检查清单。

是什么

Tree Shaking 是打包器在构建阶段做的一次"活代码保留":从入口出发,沿着 ES Module 的静态 import/export 关系走一遍,只把真正可达的导出留下,把没人引用的导出乃至整个模块丢掉。它常被翻译成"摇树",但更准确的直觉是从根部长出来的才算活枝,而不是拿把剪刀见到没执行的语句就剪。这个名字由 Rollup 带火,如今 webpack、esbuild、Rolldown 都有自己的实现。

sideEffects 则是 package.json 里的一个约定字段,值可以是布尔或 glob 数组,用来声明"这个包里的模块在被 import 求值时,会不会产生导出之外的副作用"。false 表示全部模块都干净,数组表示只有列出的那些不干净。

一句话直觉:它像搬家前贴在纸箱上的"空箱,可直接丢"标签。搬运工不会开箱验货,标签贴错,贵重物品就跟着走了。典型场景是组件库只用一个 Button,产物里却躺着整座组件库;或者库里的 CSS、polyfill 在开发环境好好的,上线后一起消失。

核心原理

第一步:图必须画得出来。 Tree Shaking 的前提不是"代码没用",而是"能静态判定有没有用"。ESM 的 import/export 只能写在顶层,模块说明符是字符串字面量,打包器在解析阶段就能确定每条边;CommonJS 的 require 可以写在 if 里,exports.foo 可以在循环里赋值,图建不准,工具只能保守处理。所以"用了 ESM 语法"不等于"会被摇",一旦 Babel 或 tsc 把模块编译成 CJS,静态结构就没了,后面的优化无从谈起。

第二步:分清三层删除。 这是面试里最能拉开差距的地方。

  • 导出级:webpack 的 usedExports 会在模块里给没用到的导出打上 / unused harmony export /,再由 terser 按语句删。但模块本身仍要被求值,因为 ESM 规范要求 import 先执行依赖模块;所以只要这个模块被引用,它顶层的 console.log、全局注册、原型补丁都不会因为"导出没人用"而消失。webpack 官方文档明确说,sideEffects 比 usedExports 更有效,因为前者能跳过整个模块和整棵子树,后者不能(Tree Shaking)。
  • 模块级:只有当打包器能确认"求值这个模块不会产生可观察影响"时,才敢把整个模块连同它的依赖一起跳过。这正是 sideEffects 管的层级。JS 是图灵完备的,window.foo = 1、import './polyfill'、customElements.define(...) 在语法上都是普通语句,打包器证明不了它们无害,默认只能假设有副作用。
  • 语句级:terser 这类压缩器负责把"结果没人用、调用又确定无害"的表达式删掉。/#__PURE__/ 就是给压缩器看的批注:这次调用是纯的,返回值没被使用就可以整条丢。它只影响语句,不改变模块级判断;较新的 webpack 还支持把 /#__NO_SIDE_EFFECTS__/ 标在函数声明上,让调用点在结果未使用时被删。

第三步:理解"副作用"的边界。 副作用不是"这段代码看起来重要",而是求值模块时,除了建立导出绑定之外,还改变了模块外可观察的状态:写全局变量或原型链、读写 DOM、注册事件监听、发网络请求、写存储、注入 CSS、启动定时器,甚至抛错(它改变控制流)。只要有一项存在,整模块就不能被当成空箱。

所以 sideEffects 是模块粒度的承诺,不是语句粒度,也不是"这个包很纯"的奖章。写了 false,打包器最多敢跳过"一个导出都没被用到"的模块;只要你用了该模块的任一导出,模块照常完整执行,顶层的副作用一行不少。这一点是大部分错误答案的分水岭。

// 1) 模块级:没声明 sideEffects 时,整包被保留
import { Button } from 'ui-kit';

// 2) 语句级:结果没用到,但调用可能有副作用,terser 不敢删
const chart = createChart(el);

// 3) 加纯函数批注:结果没用到时,这条调用可以整条删
const unused = /*#__PURE__*/ createChart(el);

这三行的差别不在写法优雅,而在你告诉工具的信息量:第一行缺的是包作者的声明,第二行缺的是"这个函数纯不纯"的证据,第三行才是语句级的许可。

第四步:为什么开发环境看不出来。 webpack 的 optimization.sideEffects 在 production 下是 true,在 development 下是 'flag',只认显式声明,不再分析源码;usedExports、innerGraph、concatenateModules 在开发模式也默认关闭(Optimization)。Vite 更彻底:开发时源码走浏览器原生 ESM 按需加载,只有 vite build 才用 Rollup 打包(Why Vite、Build)。因此"dev 里模块还在"不能证明生产没摇掉;反过来,CSS 在 dev 里正常、生产构建后样式没了,恰恰是只测开发最常漏的坑。

第五步:不同工具读的不是同一张说明书。 sideEffects 不是 ECMAScript 或 npm 的标准字段,而是 webpack 引入的约定,esbuild 也尊重它,并提供 --ignore-annotations 在声明出错时兜底(esbuild API)。Rollup 核心本身不读这个字段,通常由 @rollup/plugin-node-resolve 把它翻译成 moduleSideEffects;Rollup 自己的开关叫 treeshake.moduleSideEffects,可取 true、false、'no-external' 或函数(Rollup 配置)。这也解释了一个常见困惑:同一个 sideEffects: false,在 webpack、Vite、纯 Rollup 下表现可能不同,因为"谁在读、读到了哪一层"不一样。

常见考点与误区

  • 误区一:Tree Shaking 就是删掉没执行的代码。 它做的是从入口出发的可达性分析,再叠加副作用判定;动态属性访问、eval、CJS、运行时拼接的 import 都会让图变模糊。代码"没被执行"不等于"可以被证明没用"。
  • 误区二:sideEffects: false 是性能开关。 它只对"整个模块的导出都没被使用"生效;用了任一导出,模块就完整保留,模块内某条语句没用也删不掉。它更像一张法律责任书:签对了省体积,签错了就是生产事故。
  • 误区三:开发环境没删,说明配置没生效。 生产模式才默认开整套优化;Vite 开发时源码不做整包构建。判断优化是否生效,必须看 production build 的产物,最好再用 preview 跑一遍真实页面。
  • 误区四:Babel/tsc 转完还能摇。 转成 CJS 后静态结构丢失;@babel/preset-env 要设 modules: false,TypeScript 要把 module 设成 esnext 或 bundler,否则打包器看到的是 require。
  • **误区五:import * as ns 和动态 key 没关系。** 一旦出现 ns[key],打包器无法知道用了哪个导出,只能把所有导出都当成"可能被用";barrel 文件里的 export * 加上副作用导入,也很容易把整棵子树拖进来。
  • **误区六:/#__PURE__/ 什么都能删。** 它只在"调用结果未被使用"且压缩器开启时起作用,对模块级副作用无效;给有注册行为的调用乱加批注,等于亲手制造一个只在生产环境复现的 bug。
  • 考点七:数组写的是"有副作用"还是"可删"? sideEffects: ["./src/polyfill.js", "*.css"] 列的是有副作用、必须保留的文件,其余才被视为干净;方向写反,CSS 和 polyfill 会第一个消失。

实践建议

  • 库作者:用白名单,不要一刀切。 发布 ESM 产物(exports 的 import 条件或 module 字段),把 sideEffects 写成 ["*.css", "./dist/polyfill.js", "./dist/register.js"] 这样的数组;新增任何"被 import 就干活"的文件时同步更新。false 只在你能对全包负责时使用。
  • 使用方:让导入路径更具体。 优先具名导入和 exports 子路径,避开大 barrel;lodash 这类 CJS 包换 lodash-es 或单函数包,比在打包器里硬调参数有效得多。
  • 用产物验证,不用感觉验证。 跑一次 production build,用 bundle analyzer 看目标模块到底占多少;再做一次"开/关 sideEffects"的对照,确认省下的体积不是靠误删换来的。
  • 把生产冒烟纳入发布门禁。 至少覆盖:样式是否还在、polyfill 是否生效、自定义元素/全局组件是否注册、i18n 与埋点是否初始化。这些恰好都是最容易被 sideEffects: false 误杀的代码。
  • 给纯工厂函数加批注,但只加在真纯的地方。 createContext、styled、schema 构造这类"调用只为拿返回值"的工厂适合 /#__PURE__/;带注册、带请求、带 DOM 写入的调用不要加。
  • 升级打包器后重跑对照。 不同版本对注解传播、sideEffects 分析范围的处理会变,昨天的产物结论不能直接搬到今天;把体积与冒烟都放进 CI,比记住某个版本的默认值可靠。

一句话总结:Tree Shaking 删的是从入口不可达的东西,sideEffects 决定打包器敢不敢跳过一整个模块——它是作者的承诺,不是免费的开关。

相关阅读

← 返回文章志