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 是声明式的，在编译期就能确定依赖图，打包器据此标记未使用的导出并删除。下面的框图描述了从源码到摇树产物的链路。

text 复制代码

源码(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 exports	package.json `exports` 定义子入口	入口清晰，按入口分包	路径约定需文档化	大型库按域分包

sideEffects 字段是摇树的第二道开关。它在 package.json 里声明哪些文件有副作用。false 表示全库无副作用，打包器可大胆删未引用模块；数组则精确列出有副作用的文件（通常是样式或 polyfill），其余放心摇。声明错误代价很高：该声明 false 却没声明，打包器保守保留全量；不该声明 false 却声明了，副作用被删导致运行时崩溃。所以 sideEffects 必须与实际代码逐一核对，不能拍脑袋填。

三、生产级组件库构建与副作用收敛实现

下面是一份 Rollup 构建配置与 package.json 字段，目标是产出可摇的 ESM 产物并把副作用精确隔离。

javascript 复制代码

// 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'],
};

json 复制代码

{
  "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 扩展。

组件自身的副作用收敛同样关键。下面是一个反面与正面对照。

typescript 复制代码

// 反面：模块顶层有副作用，打包器不敢删，摇树失效
import './global.css'; // 顶层副作用，全量保留
window.__UI_THEME__ = { primary: '#1677ff' }; // 顶层改全局

export function Button(props: ButtonProps) {
  return <button {...props} />;
}

typescript 复制代码

// 正面：副作用集中到显式入口，组件本身纯函数可摇
// 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 是工程权衡，须以产物体积回归与运行时稳定性双口径验收。