Tree Shaking 失败的常见场景：sideEffects 标记与纯函数的边界判断

各位开发者，下午好！

今天，我们将深入探讨前端性能优化中的一个核心技术——Tree Shaking。它承诺为我们带来更小、更快的应用包，但现实中，我们经常会遇到Tree Shaking“不工作”的情况，导致我们精心设计的模块化代码依然臃肿。这些失败的场景，往往围绕着一个核心概念：副作用（side effects），以及打包工具对纯函数（pure functions）边界的判断。

作为一名编程专家，我将带领大家系统地梳理Tree Shaking的原理，剖析其失败的常见原因，特别是围绕package.json中的sideEffects标记，以及在编写代码时如何正确判断和处理函数的纯粹性。我的目标是让大家不仅理解Tree Shaking是什么，更重要的是理解它为什么会失败，以及如何采取措施确保它在你的项目中发挥最大效用。

---

一、Tree Shaking 基础原理重温

在深入探讨失败场景之前，我们首先需要对Tree Shaking有一个清晰的认识。

A. 什么是 Tree Shaking？

Tree Shaking，字面意思就是“摇晃树木”，让枯叶（dead code，即未使用的代码）从树上掉下来。在前端领域，它是一种死代码消除（Dead Code Elimination, DCE）技术，专注于移除JavaScript模块中未被使用的导出（exports）。其核心目标是减小最终打包产物的体积，提升应用加载性能。

与传统的DCE（例如UglifyJS/Terser等压缩工具在AST层面进行的简单消除）不同，Tree Shaking是一种更高级、更智能的DCE。它不仅仅是移除那些声明了但从未被执行的代码，而是通过分析模块间的import和export关系，识别出那些被导出但从未被导入或使用的模块成员。

B. 为何 Tree Shaking 依赖 ES Modules？

Tree Shaking之所以能够高效工作，关键在于ES Modules（ESM）的静态结构。

• ES Modules (ESM): import和export语句是静态的。这意味着在代码执行之前，打包工具（如Webpack、Rollup）就可以在编译时（compile-time）确定模块的依赖关系和导出哪些内容。例如：

  // module.js
  export const funcA = () => console.log('A');
  export const funcB = () => console.log('B');
  
  // app.js
  import { funcA } from './module'; // 静态分析：只需要funcA
  funcA();

  打包工具可以明确知道funcB从未被app.js或其他任何模块导入使用，因此可以安全地将其移除。

• CommonJS (CJS): 相比之下，CommonJS模块（require/module.exports）是动态的。require可以在运行时根据条件动态地决定加载哪个模块，或者module.exports可以被重新赋值。

  // module.js (CommonJS)
  const funcA = () => console.log('A');
  const funcB = () => console.log('B');
  if (Math.random() > 0.5) {
      module.exports = { funcA };
  } else {
      module.exports = { funcB };
  }
  
  // app.js (CommonJS)
  const { funcA } = require('./module'); // 运行时才能确定
  funcA();

  在这种情况下，打包工具无法在编译时确定funcA或funcB哪个会被导出，也就无法安全地移除任何一个。这使得CommonJS模块难以进行有效的Tree Shaking。

因此，要享受Tree Shaking带来的好处，使用ES Modules是前提。

C. Tree Shaking 的核心原理：纯粹性与副作用

Tree Shaking的决策核心在于判断代码是否具有“副作用”。

• 副作用 (Side Effect): 在编程中，副作用是指一个函数或表达式在完成其主要任务（例如计算并返回一个值）之外，对外部环境产生可观察到的影响。常见的副作用包括：

  • 修改全局变量或对象属性。
  • 修改函数参数（如果它们是对象或数组）。
  • I/O 操作（读写文件、网络请求）。
  • DOM 操作（修改页面元素）。
  • console.log()输出。
  • 抛出异常。
  • 调用具有副作用的函数。

• 纯函数 (Pure Function): 满足以下两个条件的函数被称为纯函数：

  1. 确定性: 对于相同的输入，总是返回相同的输出。
  2. 无副作用: 不会修改外部状态，也不会产生任何外部可观察到的影响。

Tree Shaking的逻辑是： 如果一个模块或其内部的某个导出成员被判断为没有副作用，并且在最终的应用代码中没有被实际使用，那么它就可以被安全地移除。反之，如果被判断为有副作用，或者即使没有副作用但被使用了，就不能被移除。

打包工具（如Webpack）默认会假设ES Modules中的导入是纯粹的，即它们在导入时不会产生副作用，除非有明确的指示。这个“明确的指示”就是我们接下来要重点讨论的package.json中的sideEffects属性。

---

二、sideEffects 属性在 package.json 中的应用与误区

sideEffects是Webpack 4+和Rollup等打包工具引入的一个重要特性，它允许库的作者向打包工具声明其模块是否包含副作用。这个声明对于Tree Shaking的准确性至关重要。

A. sideEffects 的目的和机制

当Webpack处理一个第三方库时，它会检查该库package.json文件中的sideEffects字段。

• 目的: 告诉打包工具哪些文件或整个包在被导入时会执行有副作用的代码，即使其导出的内容从未被使用。
• 机制:
  • 如果sideEffects被标记为false，Webpack会假设该包的所有模块都是纯粹的，可以在不被使用时被安全地移除。
  • 如果sideEffects被标记为true（或被省略，默认就是true），Webpack会认为该包可能包含副作用，因此不会对其进行激进的Tree Shaking，可能会保留整个包或其中的大部分内容。
  • 如果sideEffects是一个文件路径数组，Webpack只会保留数组中指定的文件（因为它们被认为有副作用），而对其他文件进行Tree Shaking。

B. sideEffects 的可选值

sideEffects字段可以接受以下几种值：

sideEffects 值	含义	Tree Shaking 行为	适用场景
false	整个包（所有模块）都没有副作用。导入任何模块都不会对全局状态、DOM等产生影响。	打包工具可以对该包进行最大程度的Tree Shaking。只有明确导入并使用的导出成员及其依赖会被包含在最终包中。	纯工具库（如Lodash-es、Date-fns）、纯UI组件库（如React组件库，不包含全局样式或初始化脚本）。
true	整个包（所有模块）可能包含副作用。或者，你无法确定哪些文件有副作用，或者大部分文件都有副作用。	打包工具会非常保守，通常会包含整个包的大部分内容，即使某些导出未被使用。这会阻碍Tree Shaking的效果。	包含全局样式、polyfill、注册全局组件、修改原型链等操作的库。如果省略此字段，默认行为就是 true。
["./src/foo.js", "./src/bar.css"]	包内只有指定路径的文件具有副作用。可以是文件路径、目录路径或glob模式。	打包工具会保留指定路径的文件，无论它们是否被导入使用。对于未指定的文件，打包工具会假设它们没有副作用，并对其进行Tree Shaking。	库中包含独立于业务逻辑的全局样式文件、polyfill文件，或者在文件被导入时会执行某些初始化操作（如注册服务）。

C. 常见失败场景 1: 忘记为纯粹的库设置 sideEffects: false

这是最常见、最容易被忽视的Tree Shaking失败原因。许多库本身是纯粹的，只导出函数、常量或类，但其package.json中没有明确声明sideEffects: false。

场景描述:
你正在使用一个第三方工具库，它提供了大量独立的纯函数。例如，一个数学计算库，或者一个字符串处理库。你只使用了其中的一两个函数，但打包后发现整个库都被包含了进来。

示例代码:

假设我们有一个名为my-math-utils的库。

my-math-utils/package.json (问题所在: 缺少 sideEffects: false)

{
  "name": "my-math-utils",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/esm/index.js", // 提供ESM入口
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/index.js"
    }
  }
  // 缺少 "sideEffects": false
}

my-math-utils/src/add.js

export const add = (a, b) => a + b;
console.log('add module loaded'); // 假设这里有一个不经意的副作用

my-math-utils/src/subtract.js

export const subtract = (a, b) => a - b;
console.log('subtract module loaded'); // 假设这里有一个不经意的副作用

my-math-utils/src/multiply.js

export const multiply = (a, b) => a * b;
console.log('multiply module loaded'); // 假设这里有一个不经意的副作用

my-math-utils/src/index.js (库的入口文件)

export { add } from './add';
export { subtract } from './subtract';
export { multiply } from './multiply';

(假设经过构建，这些文件分别编译到了dist/esm和dist目录)

my-app/src/app.js (你的应用代码)

import { add } from 'my-math-utils'; // 只导入了 add 函数

const result = add(5, 3);
console.log('Result:', result);

解释:
由于my-math-utils/package.json中没有"sideEffects": false，Webpack会默认认为这个库可能包含副作用 (sideEffects: true)。
因此，当my-app导入my-math-utils时，Webpack不敢轻易地移除subtract和multiply模块，因为它担心这些模块在导入时会执行一些重要的、有副作用的初始化逻辑（比如上面代码中演示的console.log，即使它看起来无害，但对于打包工具来说，任何非纯粹的操作都是副作用）。结果就是，subtract.js和multiply.js模块的内容，甚至可能包括其内部的console.log语句，都会被打包到最终产物中，即使my-app从未调用subtract或multiply函数。

解决方案:
库的作者应该在my-math-utils/package.json中明确声明"sideEffects": false。

my-math-utils/package.json (修正后)

{
  "name": "my-math-utils",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/esm/index.js",
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/index.js"
    }
  },
  "sideEffects": false // 明确声明整个包都没有副作用
}

通过这个简单的声明，Webpack就会知道my-math-utils是一个纯粹的库。当my-app只导入add时，subtract和multiply模块及其内部的console.log语句都将被安全地摇掉。

D. 常见失败场景 2: 错误地将有副作用的模块标记为 sideEffects: false

这个场景是上一个的反面，同样危险，甚至可能导致运行时错误。

场景描述:
你正在维护一个库，其中包含了确实有副作用的代码（例如，自动注册全局组件、修改原型链、注入全局样式），但你却为了追求极致的Tree Shaking效果，错误地将整个库标记为sideEffects: false。

示例代码:

假设我们有一个UI组件库my-ui-library。

my-ui-library/package.json (问题所在: 错误地设置 sideEffects: false)

{
  "name": "my-ui-library",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/esm/index.js",
  "sideEffects": false // 错误地声明整个包都没有副作用
}

my-ui-library/src/global-styles.js (这个文件有副作用)

// 这个模块负责注入全局CSS样式到DOM中
const styleTag = document.createElement('style');
styleTag.innerHTML = `
  body {
    margin: 0;
    font-family: sans-serif;
  }
  .my-ui-button {
    padding: 8px 16px;
    border: 1px solid blue;
    border-radius: 4px;
    cursor: pointer;
  }
`;
document.head.appendChild(styleTag);

console.log('Global styles injected!'); // 明确的副作用

my-ui-library/src/button.js

import './global-styles'; // 导入全局样式，使其副作用被执行

export const Button = () => {
  const btn = document.createElement('button');
  btn.className = 'my-ui-button';
  btn.textContent = 'Click Me';
  return btn;
};

my-ui-library/src/index.js

export { Button } from './button';
// 假设还有其他组件或工具函数

my-app/src/app.js

import { Button } from 'my-ui-library'; // 只导入 Button 组件

const appDiv = document.getElementById('app');
appDiv.appendChild(Button());

解释:
my-ui-library/package.json中声明了"sideEffects": false。
然而，my-ui-library/src/global-styles.js在被导入时，会直接执行DOM操作（创建并添加<style>标签），这是一个明显的副作用。
当my-app导入Button组件时，Button组件又导入了global-styles.js。
因为my-ui-library被标记为sideEffects: false，Webpack会认为global-styles.js也没有副作用。由于my-app并没有直接从global-styles.js中导入任何导出成员（它也没有导出任何成员），Webpack会认为global-styles.js是未使用的代码，并将其移除。
结果是，当my-app运行时，global-styles.js中的样式注入代码不会被执行，Button组件将失去其预期的样式，导致UI显示异常。

解决方案:
对于包含副作用的库，应该精确地声明哪些文件有副作用，而不是一概而论。

my-ui-library/package.json (修正后)

{
  "name": "my-ui-library",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/esm/index.js",
  "sideEffects": [ // 明确指定哪些文件有副作用
    "./dist/esm/global-styles.js", // 假设编译后的路径
    "./dist/global-styles.js",
    "**/*.css" // 或者如果库中有很多CSS文件，可以使用glob模式
  ]
}

通过将sideEffects设置为一个文件路径数组，Webpack会知道global-styles.js这个文件是不能被Tree Shaking的，因为它有重要的副作用。即使my-app没有直接导入global-styles.js，只要它被button.js导入，并且button.js本身被使用了，那么global-styles.js就会被保留下来。

E. 常见失败场景 3: Granular sideEffects 与 CSS/Polyfill 的精细控制

延续上一个场景，当一个库既包含纯粹的ES Modules代码，又包含必须执行副作用的文件（如全局CSS或特定环境的Polyfill）时，精确地使用sideEffects数组至关重要。

场景描述:
一个大型组件库，其中大部分组件是纯粹的，可以被Tree Shaking。但它可能包含：

1. 一个或多个全局CSS文件，用于定义Reset样式或主题变量。
2. 一个或多个Polyfill文件，用于确保在旧浏览器中的兼容性。
3. 一些在导入时就进行初始化（如注册服务、配置）的文件。
   这些文件必须被包含在最终的bundle中，无论它们是否被应用程序直接导入。

示例代码:

my-component-library/package.json

{
  "name": "my-component-library",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/esm/index.js",
  "sideEffects": [
    "./dist/esm/base.css",       // 全局基础CSS
    "./dist/esm/theme.css",       // 全局主题CSS
    "./dist/esm/polyfills.js",    // 应用所需的polyfill
    "./dist/esm/init-service.js"  // 服务初始化文件
  ]
}

my-component-library/src/base.css

/* base.css */
body { margin: 0; padding: 0; box-sizing: border-box; }

my-component-library/src/polyfills.js

// polyfills.js
if (!Array.prototype.flat) {
  Array.prototype.flat = function() { /* ... polyfill implementation ... */ };
  console.log('Array.prototype.flat polyfilled.');
}

my-component-library/src/button.js

// button.js - 纯组件
export const Button = ({ text }) => {
  const el = document.createElement('button');
  el.textContent = text;
  el.className = 'my-button';
  return el;
};

my-component-library/src/index.js

// index.js - 库的入口，导入了有副作用的文件
import './base.css'; // 导入全局CSS
import './polyfills'; // 导入polyfill

export { Button } from './button';
// ... 导出其他组件

my-app/src/app.js

import { Button } from 'my-component-library';

document.getElementById('root').appendChild(Button({ text: 'Hello' }));
// my-app 没有直接导入 base.css 或 polyfills.js

解释:
在my-component-library的package.json中，我们使用一个数组精确地指定了哪些编译后的文件具有副作用。
当my-app只导入Button组件时：

1. Button组件本身是纯粹的，如果未被使用，可以被Tree Shake。但这里被使用了，所以会被保留。
2. base.css和polyfills.js虽然没有被my-app直接导入，但它们在my-component-library/src/index.js中被导入，并且最重要的是，它们在package.json的sideEffects数组中被明确列出。
3. Webpack会尊重这个sideEffects声明，确保base.css和polyfills.js即使没有被直接使用，也会被包含在最终的bundle中，以保证库的正常功能和兼容性。
   这样，既能对纯粹的组件进行Tree Shaking，又能保留必要的副作用代码。

最佳实践:

• 尽可能使用sideEffects: false: 如果你的库确实是纯粹的，大胆使用false。
• 精确指定副作用文件: 如果库中只有少数文件有副作用，使用数组列出它们。使用glob模式（如**/*.css）可以简化配置。
• 将副作用代码隔离: 尝试将所有具有副作用的代码（如全局样式、polyfill、初始化逻辑）集中到少数几个文件中，这样更容易管理sideEffects数组。
• 区分导入方式: CSS文件通常需要被导入才能生效，即使没有导出任何JS变量。因此，将CSS文件路径添加到sideEffects数组中是常见的做法。

---

三、纯函数边界判断与运行时副作用

Tree Shaking依赖于打包工具对代码的静态分析。然而，JavaScript的动态特性有时会模糊纯函数的边界，导致打包工具无法做出准确判断，从而阻止Tree Shaking。

A. 何为 Tree Shaking 语境下的“纯函数”？

对于Tree Shaking而言，一个“纯函数”或“纯表达式”意味着：

1. 无外部依赖副作用: 执行它不会改变任何外部状态（如全局变量、DOM），也不会执行I/O操作。
2. 返回值不被使用，则可移除: 如果函数的返回值没有被后续代码使用，并且函数本身没有副作用，那么函数调用以及函数定义都可以被移除。
3. 静态可分析: 打包工具必须能够在编译时确定其纯粹性。

B. 常见失败场景 4: 带有隐藏副作用的函数

有些函数表面上看起来是纯粹的，但在其内部或依赖的模块中，却默默地执行了副作用。打包工具的静态分析能力是有限的，它无法模拟代码的运行时行为，也无法轻易穿透复杂的调用链来判断深层次的副作用。

场景描述:
你有一个工具函数，它似乎只是进行计算并返回结果。但这个函数内部，或者它所依赖的某个模块的顶层作用域中，可能包含console.log、修改了某个全局配置对象，或者注册了一个事件监听器。

示例代码:

config.js

// config.js - 这是一个全局配置对象，可能被多个模块使用
export const appSettings = {
  debugMode: false,
  logLevel: 'info'
};

// 这里的副作用是修改了全局对象，但通常不会被认为是一个“bug”
// 但如果这个模块被 Tree Shaking 掉了，那 appSettings 的默认值就得不到初始化
// 实际上，如果 appSettings 被导入并使用了，这个模块就不会被 Tree Shake。
// 真正的“隐藏副作用”是，如果一个模块在导入时就修改了 appSettings 但 appSettings 没被使用
// 或者，函数内修改了 appSettings 但函数没被调用。

logger.js

// logger.js - 模拟一个内部的日志系统
import { appSettings } from './config';

export const logMessage = (level, message) => {
  if (appSettings.debugMode || level === 'error') {
    console.log(`[${level.toUpperCase()}]: ${message}`); // 明显的副作用
  }
};

// 假设这个模块在导入时就执行了一些初始化日志配置
console.log('Logger module initialized.'); // 顶层副作用

utils.js

import { logMessage } from './logger';

export const calculateSum = (a, b) => {
  logMessage('debug', `Calculating sum of ${a} and ${b}`); // 调用了有副作用的函数
  return a + b;
};

// 另一个函数，看起来纯粹，但如果它依赖的模块有副作用，也可能受影响
export const calculateProduct = (a, b) => a * b;

app.js

import { calculateProduct } from './utils'; // 只导入了 calculateProduct

const product = calculateProduct(4, 5);
console.log('Product:', product);

解释:

1. logger.js在顶层作用域有console.log('Logger module initialized.')这个副作用。
2. calculateSum函数内部调用了logMessage，而logMessage内部有console.log副作用。
3. app.js只导入了calculateProduct。calculateProduct本身是纯函数，没有直接的副作用。
4. 但是，utils.js模块同时导出了calculateSum和calculateProduct，并且calculateSum依赖了logger.js。
5. 如果utils.js模块没有被标记sideEffects: false（或者my-library整个包没有），Webpack会保守地对待它。即使calculateSum没有被使用，由于calculateSum调用了logMessage（一个有副作用的函数），打包工具可能会认为utils.js整个模块都是有副作用的，从而阻止Tree Shaking。
6. 更隐蔽的是，如果logger.js的console.log('Logger module initialized.')是其唯一的“副作用”，且logMessage函数未被调用，那么logger.js是否会被Tree Shake掉，取决于logger.js所在的包的sideEffects设置。如果logger.js被Tree Shake掉，那么calculateSum即使被调用，logMessage也可能不存在。

后果:

• 如果utils.js或其父包被误判为有副作用，calculateSum及其依赖的logger.js可能会被保留，即使calculateSum从未被调用，导致包体积增大。
• 如果logger.js被Tree Shake掉，而calculateSum仍然被保留并调用，则会因为logMessage未定义而导致运行时错误。

解决方案:

1. 显式声明sideEffects: 确保库的package.json正确设置了sideEffects。
2. 隔离副作用: 将有副作用的代码（如console.log、全局状态修改）从纯函数中分离出来。如果日志是可选的，可以将其作为可配置项，或者确保只有在被调用时才执行。
3. 使用/*#__PURE__*/标记: 对于那些看起来像函数调用但实际上是纯粹的表达式，可以使用这个magic comment（详见第四节）。
4. 审查依赖链: 深入理解你的函数所依赖的模块是否在导入时就执行了副作用。

C. 常见失败场景 5: 动态导入、eval 和其它运行时代码生成

Tree Shaking的核心是静态分析。任何阻碍静态分析的手段都会导致Tree Shaking失效。

场景描述:
代码中使用了eval()、new Function()或者Node.js环境下的动态require()（尽管我们讨论ESM，但有时会遇到跨环境的库），这些方式都无法在编译时确定其行为。

示例代码:

dynamic-module.js

// dynamic-module.js
export const dynamicFeature = (codeString) => {
  // eval() 阻止了 Tree Shaking
  eval(codeString); // Webpack 无法知道 codeString 会执行什么
};

export const anotherPureFunction = () => 'This is pure.'; // 这个函数也可能受到影响

app.js

import { dynamicFeature, anotherPureFunction } from './dynamic-module';

// 即使这里没有调用 dynamicFeature
// Webpack 依然会保守对待 dynamic-module.js
// 因为它看到了 eval()，无法保证 eval 不会产生副作用
console.log(anotherPureFunction());

解释:
当Webpack看到eval()、new Function()等运行时代码生成机制时，它无法预测这些代码会做什么。它们可能修改全局状态，可能动态导入其他模块，可能执行任何有副作用的操作。
因此，为了安全起见，Webpack会放弃对包含这些动态代码的模块进行Tree Shaking。即使dynamicFeature函数从未被调用，dynamic-module.js整个模块也可能被保留下来，包括anotherPureFunction。

后果:

• 模块体积增大，即使其中大部分代码未被使用。
• 整个库的Tree Shaking效果可能大打折扣。

解决方案:

• 避免使用eval()或new Function()进行业务逻辑处理。它们通常被认为是安全漏洞，并且不利于性能优化。
• 使用静态import语句。如果需要按需加载，使用ES Modules的动态import()语法 (import('./module').then(...))。Webpack对import()有特殊处理，可以对其进行代码分割和Tree Shaking。
• 重构代码，将动态行为转换为可静态分析的形式。

D. 常见失败场景 6: Transpilation Issues 和非 ES Module 语法

Tree Shaking依赖于ES Module的import/export语法。如果你的构建流程（如Babel）在打包工具之前将ES Modules转换为CommonJS，那么Tree Shaking就会失效。

场景描述:
你使用Babel来转换你的JavaScript代码，但Babel的配置不正确，它将所有的import和export语句都转换成了require和module.exports。

示例代码:

babel.config.js (问题所在: modules: 'commonjs')

module.exports = {
  presets: [
    ['@babel/preset-env', {
      modules: 'commonjs' // <-- 这里是问题所在！
    }]
  ]
};

my-library/src/utilA.js

export const funcA = () => 'A';
export const funcB = () => 'B';

my-library/src/index.js

export { funcA, funcB } from './utilA';

my-app/src/app.js

import { funcA } from 'my-library'; // ES Module 语法

console.log(funcA());

解释:

1. 当my-library的源代码经过Babel处理时，由于modules: 'commonjs'配置，my-library/src/utilA.js中的export会被转换为exports.funcA = ...;，而my-library/src/index.js中的export { funcA, funcB } from './utilA';会被转换为const _utilA = require('./utilA'); exports.funcA = _utilA.funcA; exports.funcB = _utilA.funcB;。
2. 当Webpack开始处理my-app时，它看到的my-library已经不是ES Modules，而是CommonJS模块了。
3. 如前所述，CommonJS是动态的，Webpack无法对其进行有效的静态分析和Tree Shaking。因此，即使my-app只使用了funcA，funcB也可能被包含在最终的bundle中。

后果:

• 整个构建的Tree Shaking功能被削弱甚至完全失效。
• 即使库作者正确设置了sideEffects: false，也可能因为上游的Babel转换而导致Tree Shaking失败。

解决方案:

• 配置Babel正确处理ES Modules: 确保Babel不要将ES Modules转换为CommonJS。这通常是通过将@babel/preset-env的modules选项设置为false来实现的。让Webpack或Rollup等打包工具来处理ES Modules。
  babel.config.js (修正后)

  module.exports = {
    presets: [
      ['@babel/preset-env', {
        modules: false // <-- 确保这里是 false
      }]
    ]
  };

• 对于TypeScript用户: 确保tsconfig.json中的"module"选项设置为"es2015"或更高版本（如"esnext"），而不是"commonjs"。

E. 常见失败场景 7: 未使用的类声明或导出的变量

这通常不是Tree Shaking的失败，而是开发者对Tree Shaking期望的误解，或者对类声明的副作用判断不准确。

场景描述:
你导出了一个类或一个常量，但应用程序从未实例化这个类或从未访问这个常量。你期望它们被Tree Shake掉，但它们却仍然出现在最终的bundle中。

示例代码:

my-library/src/data.js

export const API_KEY = 'some_secret_key'; // 未使用的常量

export class User { // 未实例化的类
  constructor(name) {
    this.name = name;
    console.log(`User ${name} created.`); // 构造函数中的副作用
  }

  greet() {
    return `Hello, ${this.name}!`;
  }

  static getVersion() { // 静态方法
    return '1.0.0';
  }
}

// 模块顶层的一个副作用
console.log('Data module loaded.');

my-app/src/app.js

// my-app 没有任何地方导入或使用 API_KEY 或 User 类
console.log('App started.');

解释:

1. API_KEY: 如果my-library的package.json设置为"sideEffects": false，并且API_KEY从未被导入和使用，那么它应该被安全地Tree Shake掉。如果它仍然存在，可能是因为my-library没有正确设置sideEffects，或者整个data.js模块被视为有副作用（例如，因为顶层的console.log）。
2. User类:
   • 类声明本身： 如果User类在声明时没有任何直接的副作用（例如，它没有静态初始化块修改全局状态），并且它从未被实例化，那么类声明本身通常可以被Tree Shake掉，前提是data.js模块被视为无副作用。
   • 构造函数中的副作用： console.log(User ${name} created.); 这是一个副作用。但这个副作用只会在User类被new实例化时才执行。如果类没有被实例化，这个副作用就不会发生，因此并不妨碍Tree Shaking移除未使用的类声明。
   • 模块顶层副作用： console.log('Data module loaded.'); 这是最关键的。如果data.js文件本身包含这样的顶层副作用，那么无论API_KEY或User类是否被使用，这个文件都可能被视为有副作用，从而阻止整个文件的Tree Shaking。

解决方案:

• 确保sideEffects: false: 对于纯粹的库，这是基础。
• 消除模块顶层副作用: 避免在模块的顶层作用域执行任何副作用代码（如console.log、修改全局变量）。如果必须有，将它们封装在函数中，并在需要时显式调用。
• 理解Tree Shaking的边界: Tree Shaking移除的是“未使用的导出”。如果一个文件因为其自身有副作用而被保留，那么这个文件中所有未被使用的导出也可能会被保留（取决于打包工具的激进程度）。

F. 常见失败场景 8: export * from '...' 和复杂重导出

export * from '...'语法允许一个模块将另一个模块的所有命名导出再次导出。虽然现代打包工具通常能很好地处理这种结构，但在某些复杂情况下，它可能会导致误解或间接的Tree Shaking问题。

场景描述:
一个库的入口文件 (index.js) 使用 export * from 聚合了多个子模块的导出。应用程序只使用了其中一个子模块的少量导出。

示例代码:

my-library/src/utils/math.js

export const add = (a, b) => a + b;
export const subtract = (a, b) => a - b;
console.log('Math utils loaded.'); // 副作用

my-library/src/utils/string.js

export const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
export const reverse = (s) => s.split('').reverse().join('');
console.log('String utils loaded.'); // 副作用

my-library/src/index.js (库的入口文件)

export * from './utils/math';
export * from './utils/string';

my-app/src/app.js

import { capitalize } from 'my-library'; // 只使用了 capitalize

console.log(capitalize('hello'));

解释:

1. my-library/src/index.js通过export * from将math.js和string.js的所有导出都暴露出去。
2. my-app只导入了capitalize。
3. 如果my-library的package.json没有设置sideEffects: false，或者math.js和string.js本身被认为是拥有副作用的（因为它们都有顶层console.log），那么即使add、subtract、reverse没有被使用，它们以及math.js的console.log('Math utils loaded.')都可能被保留。
4. export * from本身通常不会阻止Tree Shaking，因为打包工具可以追踪到最终的原始导出。但如果源模块（如math.js）因为其自身原因（如顶层副作用）而无法被Tree Shake，那么通过export * from导出的所有内容，即使未被使用，也可能会被包含。

后果:

• 导致模块中未使用的部分及其依赖的副作用被包含。

解决方案:

• 确保所有参与重导出的子模块都是纯粹的（或正确标记了sideEffects）。
• 将副作用代码隔离到单独的文件中，并只在必要时导入。
• 考虑命名导出而非export * from，如果只有少数几个导出需要被聚合。但这通常不是必须的，因为打包工具已经很智能了。

---

四、高级考量与最佳实践

除了上述常见失败场景，还有一些高级技巧和整体性策略可以帮助我们更有效地利用Tree Shaking。

A. Pure Annotations (/*#__PURE__*/)

这是一个Webpack和Rollup支持的“魔术注释”（Magic Comment），用于显式地告诉打包工具，某个函数调用或类实例化是纯粹的，即使它看起来像一个副作用。这对于某些库的内部优化尤其有用。

场景:
在一些库（尤其是React或Vue这类UI库）中，会使用工厂函数创建元素或组件。例如，React.createElement()。

// React 源码中可能的简化表示
export function createElement(type, props, ...children) {
  // ... 逻辑 ...
  return { type, props, children }; // 返回一个纯粹的对象
}

// 应用程序代码
const element = React.createElement('div', null, 'Hello'); // 看起来是函数调用

如果element这个变量没有被使用，那么React.createElement的调用可以被移除。然而，打包工具可能默认认为任何函数调用都可能有副作用。通过/*#__PURE__*/注释，我们可以明确这个调用是纯粹的。

示例:

// 库作者在编译后的代码中添加此注释
const element = /*#__PURE__*/ React.createElement('div', null, 'Hello');

// 或者对于立即执行函数表达式（IIFE）
const init = /*#__PURE__*/ (() => {
  console.log('This IIFE runs, but its return value is pure, or if unused, can be shaken.');
  return { config: 'value' };
})();

// 如果 init 的返回值和 IIFE 本身都没有被使用，并且被标记为纯粹，它就可以被移除

何时使用:

• 当你的函数调用或IIFE的返回值是纯粹的，并且你希望当该返回值未被使用时，整个调用（包括函数本身）可以被Tree Shake掉。
• 主要由库作者使用，帮助下游应用进行更激进的Tree Shaking。

B. 模块化与精细化导出

从库设计的角度，良好的模块化是Tree Shaking成功的基础。

• 小而专注的模块: 避免一个巨大的文件导出所有功能。将功能拆分到不同的文件中，每个文件只负责一小部分逻辑。
• 避免默认导出: 尽可能使用命名导出（Named Exports）。默认导出（export default）通常意味着导入整个模块。虽然现代打包工具对默认导出也有Tree Shaking能力，但命名导出提供了更细粒度的控制。
• 隔离副作用: 将所有具有副作用的代码（如全局配置、初始化逻辑、polyfill）隔离到专门的文件中，并确保这些文件被正确地标记为有副作用。

C. 工具与调试 Tree Shaking

Tree Shaking是一个幕后工作，有时我们难以直观地看到它的效果。

• Webpack Bundle Analyzer: 这是一个非常强大的工具，可以可视化你的Webpack bundle内容，让你清楚地看到哪些模块被包含了进来，以及它们的大小。通过它，你可以发现哪些原本期望被Tree Shake掉的模块仍然存在。
• Webpack optimization.usedExports 和 optimization.sideEffects: 在Webpack配置中，optimization.usedExports（也称为providedExports）会为每个模块生成一个标记，表示哪些导出被使用了。optimization.sideEffects是控制sideEffects字段行为的关键。确保这些配置是开启的（在生产模式下通常是默认开启）。
• npm ls / yarn why: 检查你的依赖树。有时，问题可能出在某个间接依赖上，它的package.json可能没有正确配置sideEffects。
• Sourcemaps: 结合开发工具的sourcemap，检查最终生成的代码，看看你认为应该被移除的代码是否还在。

D. 不同打包工具的影响

虽然Tree Shaking的原理是通用的，但不同打包工具的实现细节和激进程度可能有所不同。

• Rollup: 通常被认为是Tree Shaking的先行者和更激进的实现者。它从一开始就专注于ES Modules和Tree Shaking，在某些情况下可能会比Webpack移除更多代码。
• Webpack: 随着版本迭代，Webpack的Tree Shaking能力也变得非常强大，尤其是在Webpack 4+引入sideEffects之后。它在处理各种复杂的场景（如代码分割、动态导入）方面更为全面。

在大多数现代项目中，Webpack是主流选择，因此理解其sideEffects机制至关重要。

---

五、确保 Tree Shaking 有效的实用指南

为了充分利用Tree Shaking，请遵循以下步骤：

1. 始终使用 ES Modules (ESM)： 确保你的所有应用代码和依赖库都使用import/export语法。避免使用CommonJS的require/module.exports。
2. 正确配置 Babel (或 TypeScript)： 如果你使用Babel，请确保@babel/preset-env的modules选项设置为false，以防止Babel将ESM转换为CJS。TypeScript用户应设置tsconfig.json中的"module"为"es2015"或更高。
3. 为你的库和依赖库检查/设置 sideEffects：
   • 作为库作者： 如果你的库是纯粹的（没有顶层副作用，只导出函数、常量、类），请务必在package.json中添加"sideEffects": false。如果包含副作用（如全局样式、polyfill），请使用精确的数组来列出这些文件。
   • 作为应用开发者： 如果你发现某个第三方库的Tree Shaking效果不佳，可以检查其package.json。如果它是一个纯粹的库但缺少sideEffects: false，可以考虑向库提交PR，或者在你的Webpack配置中通过optimization.sideEffects进行覆盖（但这通常不推荐，因为它可能会带来风险）。
4. 避免隐藏副作用： 养成良好的编码习惯，避免在模块的顶层作用域执行任何有副作用的代码。将副作用封装在函数中，并在需要时显式调用。
5. 谨慎使用动态代码生成： 避免使用eval()、new Function()等阻止静态分析的动态代码生成方式。如果需要动态加载，使用ES Modules的import()语法。
6. 在必要时使用 /*#__PURE__*/ 注释： 对于那些在视觉上是函数调用但实际上是纯粹的表达式，可以考虑使用此注释来辅助打包工具进行Tree Shaking。这主要适用于库的作者。
7. 利用打包分析工具： 定期使用Webpack Bundle Analyzer等工具检查你的bundle，可视化其内容，从而发现Tree Shaking的潜在失败点。
8. 进行运行时测试： Tree Shaking可能会移除关键的副作用代码，导致应用在运行时崩溃。在部署之前，务必在实际环境中对你的应用进行充分测试。

---

Tree Shaking是现代前端构建流程中不可或缺的一部分，它能显著提升应用的性能。然而，它并非“开箱即用”的神奇魔法，而是需要我们理解其背后的原理，特别是对“副作用”和“纯函数”的判断。通过正确配置package.json中的sideEffects，并以Tree Shaking友好的方式编写代码，我们可以确保打包工具能够有效地移除死代码，为用户带来更流畅的体验。这个过程需要库作者和应用开发者共同努力，才能发挥其最大潜力。