React 组件库的 Tree Shaking：按需加载与副作用的工程化治理

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)到底引用了哪个模块，只能全量保留。下表对比三种按需方案的差异。

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与exports，CSS 与 polyfill 进白名单，大型库按域定义子入口。第四步，建立产物体积回归测试，构建后扫描未引用组件是否真被删、CSS 是否保留，sideEffects从叶子模块逐步推进，而非全库贸然置false。样式推荐编译期方案如 vanilla-extract、linaria，消除运行时注入副作用。Tree Shaking 是工程权衡，须以产物体积回归与运行时稳定性双口径验收。