React 组件库的 Tree Shaking按需加载与副作用的工程化治理一、组件库体积膨胀打包产物里的沉默重量业务方接入一个组件库常常只用了三五个组件构建产物里却躺着一整套库。打开 bundle 分析没引用的DatePicker、Table、Cascader全在里头几十 KB 到上百 KB 悄悄塞进首屏。这不是业务方没配按需加载而是组件库自身没把摇树的门打开。根子有两类。第一类是模块格式不对库以 CommonJS 发布require是运行时表达式打包器无法静态判断哪些导出没被用摇不下去。第二类是副作用没治理库的入口在顶层执行了全局样式注入、window挂载或 prototype 扩展打包器不敢删怕删了丢了副作用导致运行时崩。这两类合在一起让按需加载退化为全量引入。更隐蔽的副作用来自 CSS。组件库常在模块顶层import ./style.css或用 CSS-in-JS 在首次 import 时注入全局样式。打包器把样式注入当作模块副作用即便组件函数没被引用样式副作用也得保留否则界面会丢样式。结果是组件摇掉了、样式却全量保留体积没省多少。Tree Shaking 的工程化治理要同时解决三件事模块格式必须是 ESM让打包器能静态分析副作用要显式声明与隔离让打包器敢删按需入口要清晰让业务方引用路径对应到可摇的子模块。本文聚焦这三条链路。二、ESM 静态分析与 sideEffects 的摇树链路Tree Shaking 的前提是模块结构可静态分析。ESM 的import/export是声明式的在编译期就能确定依赖图打包器据此标记未使用的导出并删除。下面的框图描述了从源码到摇树产物的链路。源码(ESM) 打包器静态分析 │ │ │ import { Button } from lib │ ▼ ▼ ┌──────────┐ 依赖图构建 ┌─────────────────┐ │ lib/es │──────────────▶│ 标记未用导出 │ │ Button │ │ (Modal/Table) │ │ Modal │ └────────┬────────┘ │ Table │ │ └──────────┘ ▼ ┌─────────────────────┐ │ sideEffects 检查 │ │ false → 放心删 │ │ 未声明 → 保守保留 │ └────────┬────────────┘ ▼ ┌─────────────────────┐ │ 产物仅含 Button │ │ 其依赖的子模块 │ └─────────────────────┘CommonJS 为什么摇不动require是函数调用参数可以是变量、可以条件分支、可以动态拼接。打包器无法在编译期确定require(./lib/ name)到底引用了哪个模块只能全量保留。下表对比三种按需方案的差异。方案原理优点缺点适用babel-plugin-import编译期改写 import 路径到子文件兼容老库需额外 babel 插件路径易错配历史 CJS 库ESM 原生摇树库以 ESM 发布打包器静态分析删未用零配置现代标准须 sideEffects 正确声明现代组件库subpath exportspackage.jsonexports定义子入口入口清晰按入口分包路径约定需文档化大型库按域分包sideEffects字段是摇树的第二道开关。它在package.json里声明哪些文件有副作用。false表示全库无副作用打包器可大胆删未引用模块数组则精确列出有副作用的文件通常是样式或 polyfill其余放心摇。声明错误代价很高该声明false却没声明打包器保守保留全量不该声明false却声明了副作用被删导致运行时崩溃。所以sideEffects必须与实际代码逐一核对不能拍脑袋填。三、生产级组件库构建与副作用收敛实现下面是一份 Rollup 构建配置与package.json字段目标是产出可摇的 ESM 产物并把副作用精确隔离。// rollup.config.mjs import nodeResolve from rollup/plugin-node-resolve; import { babel } from rollup/plugin-babel; import postcss from rollup-plugin-postcss; export default { input: src/index.ts, // preserveModules 保留原始模块结构让业务方打包器能按文件摇 output: { dir: dist/es, format: esm, preserveModules: true, preserveModulesRoot: src, // 产物路径与源码对齐便于 sourcemap entryFileNames: [name].js, }, plugins: [ nodeResolve({ extensions: [.ts, .tsx, .js, .jsx] }), babel({ babelHelpers: bundled, extensions: [.ts, .tsx] }), // CSS 独立抽取为按文件粒度避免合并成大 CSS 阻碍摇树 postcss({ extract: false, inject: false, modules: false }), ], // 排除 peer 依赖React 交业务方提供避免重复打包 external: [react, react-dom, react/jsx-runtime], };{ name: scope/ui, type: module, module: ./dist/es/index.js, types: ./dist/es/index.d.ts, sideEffects: [ **/*.css, ./dist/es/polyfill.js ], exports: { .: { import: ./dist/es/index.js, types: ./dist/es/index.d.ts }, ./button: { import: ./dist/es/button/index.js }, ./table: { import: ./dist/es/table/index.js } } }sideEffects数组里**/*.css告诉打包器所有 CSS 文件有副作用注入样式不可删其余 JS 模块无副作用未引用即可摇。polyfill.js单独列出因为它在顶层做了 prototype 扩展。组件自身的副作用收敛同样关键。下面是一个反面与正面对照。// 反面模块顶层有副作用打包器不敢删摇树失效 import ./global.css; // 顶层副作用全量保留 window.__UI_THEME__ { primary: #1677ff }; // 顶层改全局 export function Button(props: ButtonProps) { return button {...props} /; }// 正面副作用集中到显式入口组件本身纯函数可摇 // button/index.ts —— 仅导出组件零顶层副作用 import { Button } from ./Button; export { Button }; export type { ButtonProps } from ./types; // 样式与全局配置交给业务方显式引入而非组件顶层 import // 业务方import scope/ui/styles/global.css按需可不放首屏这段实现的关键契约有三条。其一preserveModules保留模块粒度让业务方打包器能按文件摇而不是合成一个大 chunk。其二sideEffects与实际代码逐一核对CSS 与 polyfill 进白名单其余置false声明错误会导致要么摇不掉要么运行时崩须用构建产物扫描验证。其三组件入口零顶层副作用全局样式与配置交业务方显式引入。样式推荐 CSS Modules、CSS-in-JS 等零运行时方案如 vanilla-extract、linaria把样式编译期固化避免运行时注入副作用。exports字段定义子入口大型库可按域分包业务方按需引用scope/ui/table只拉取表格相关模块。四、Tree Shaking 的代价分包碎片与 CSS 副作用边界Tree Shaking 不是免费午餐。第一个代价是分包碎片化。preserveModules保留每个源文件为独立产物大型库可能产出成百上千个小文件。HTTP/2 缓解了请求数压力但过分碎片会拖累打包器的模块图构建开发模式热更新也会变慢。权衡点是按域聚合用exports子入口按组件域分组而非每个文件一个入口。第二个代价是sideEffects的声明风险。声明偏保守漏填false导致摇不掉体积没省声明偏激进该保留的副作用没进白名单导致运行时崩。验证手段是构建后扫描产物检查未引用组件是否真的被删CSS 是否保留。声明false前必须逐一排查模块顶层是否有副作用全局赋值、prototype 扩展、import ./polyfill、CSS 注入、console副作用、模块级单例初始化。任何一处遗漏都会在线上炸。第三个代价在 CSS 副作用边界。组件库的样式若用运行时 CSS-in-JS如 styled-components样式在组件首次 import 时注入打包器把整段当副作用保留组件摇掉了样式逻辑却可能残留。解法是改用编译期 CSS 方案或把样式与组件解耦业务方显式import样式文件。但显式引入样式又增加了使用心智负担业务方忘引样式界面就崩需配套文档与 ESLint 规则提示。禁用场景要明确。强依赖全局主题注入的库运行时 CSS-in-JS摇树收益有限更应聚焦按域分包而非细粒度摇。服务端渲染场景下运行时样式注入会与 SSR 时序冲突须改编译期方案。sideEffects声明错误后果严重没有产物扫描验证机制前不要贸然全库置false应从叶子模块逐步推进配合构建产物体积回归测试卡控。五、总结React 组件库的 Tree Shaking 治理由三件事支撑模块格式 ESM 化让打包器可静态分析sideEffects显式声明让打包器敢删按需入口清晰让业务方引用对应可摇子模块。ESM 声明式import/export在编译期可确定依赖图未用导出被标记删除CommonJS 的require是运行时表达式打包器无法静态判断只能全量保留因此库必须以 ESM 发布。sideEffects是第二道开关false或精确白名单让打包器放心摇但须与实际代码逐一核对CSS 与 polyfill 进白名单其余置false声明错误会导致要么摇不掉要么运行时崩。落地步骤分四步。第一步构建切到 ESM 并开preserveModules保留模块粒度让业务方打包器按文件摇peer 依赖如 React 设为 external 避免重复打包。第二步逐模块排查顶层副作用全局赋值、prototype 扩展、CSS 注入、模块单例初始化全部收敛到显式入口组件入口保持纯导出。第三步配置package.json的sideEffects与exportsCSS 与 polyfill 进白名单大型库按域定义子入口。第四步建立产物体积回归测试构建后扫描未引用组件是否真被删、CSS 是否保留sideEffects从叶子模块逐步推进而非全库贸然置false。样式推荐编译期方案如 vanilla-extract、linaria消除运行时注入副作用。Tree Shaking 是工程权衡须以产物体积回归与运行时稳定性双口径验收。