Tree-shaking：如何删除无用模块导出？

// ✅ 正确：使用 ESM
export const bar = 'bar';
export const foo = 'foo';

// ❌ 错误：使用 CommonJS
module.exports = {
  bar: 'bar',
  foo: 'foo'
};

// webpack.config.js
module.exports = {
  optimization: {
    usedExports: true, // 开启标记功能
  },
};

// webpack.config.js
module.exports = {
  entry: "./src/index",
  mode: "production",
  devtool: false,
  optimization: {
    usedExports: true,
    minimize: true,
  },
};

// index.js
import { bar } from './bar';
console.log(bar);

// bar.js
export const bar = 'bar';
export const foo = 'foo'; // ← 这个会被 Tree Shaking 删除

// Webpack 5.107
// lib/FlagDependencyExportsPlugin.js
class FlagDependencyExportsPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap("FlagDependencyExportsPlugin", (compilation) => {
      const moduleGraph = compilation.moduleGraph;
      const cache = compilation.getCache("FlagDependencyExportsPlugin");

      compilation.hooks.finishModules.tapAsync(
        "FlagDependencyExportsPlugin",
        (modules, callback) => {
          const logger = compilation.getLogger("webpack.FlagDependencyExportsPlugin");

          /** @type {Queue<Module>} */
          const queue = new Queue();

          // ========== Step 1: 尝试从缓存恢复 ==========
          logger.time("restore cached provided exports");
          asyncLib.each(
            modules,
            (module, callback) => {
              const exportsInfo = moduleGraph.getExportsInfo(module);

              // 如果模块没有 exportsType，说明是无声明导出的模块
              if (
                (!module.buildMeta || !module.buildMeta.exportsType) &&
                exportsInfo.otherExportsInfo.provided !== null
              ) {
                exportsInfo.setHasProvideInfo();
                exportsInfo.setUnknownExportsProvided();
                return callback();
              }

              // 如果模块没有 hash，说明不可缓存
              if (
                typeof module.buildInfo.hash !== "string"
              ) {
                queue.enqueue(module);
                exportsInfo.setHasProvideInfo();
                return callback();
              }

              // 尝试从内存缓存恢复
              const memCache = moduleMemCaches && moduleMemCaches.get(module);
              const memCacheValue = memCache && memCache.get(this);
              if (memCacheValue !== undefined) {
                exportsInfo.restoreProvided(memCacheValue);
                return callback();
              }

              // 尝试从磁盘缓存恢复
              cache.get(
                module.identifier(),
                module.buildInfo.hash,
                (err, result) => {
                  if (err) return callback(err);
                  if (result !== undefined) {
                    exportsInfo.restoreProvided(result);
                  } else {
                    // 无缓存信息，入队等待确定导出
                    queue.enqueue(module);
                    exportsInfo.setHasProvideInfo();
                  }
                  callback();
                }
              );
            },
            (err) => {
              if (err) return callback(err);

              // ========== Step 2: 遍历依赖确定导出 ==========
              /** @type {Set<Module>} */
              const modulesToStore = new Set();
              /** @type {Map<Module, Set<Module>>} */
              const dependencies = new Map();

              const processDependenciesBlock = (depBlock) => {
                for (const dep of depBlock.dependencies) {
                  processDependency(dep);
                }
                for (const block of depBlock.blocks) {
                  processDependenciesBlock(block);
                }
              };

              const processDependency = (dep) => {
                const exportDesc = dep.getExports(moduleGraph);
                if (!exportDesc) return;
                exportsSpecsFromDependencies.set(dep, exportDesc);
              };

              const processExportsSpec = (dep, exportDesc) => {
                const exports = exportDesc.exports;

                if (exports === true) {
                  // unknown exports
                  exportsInfo.setUnknownExportsProvided(/* ... */);
                } else if (Array.isArray(exports)) {
                  // 具名导出列表
                  for (const exportNameOrSpec of exports) {
                    let name;
                    if (typeof exportNameOrSpec === "string") {
                      name = exportNameOrSpec;
                    } else {
                      name = exportNameOrSpec.name;
                      // ... 处理 canMangle, from, priority 等
                    }

                    const exportInfo = exportsInfo.getExportInfo(name);
                    exportInfo.provided = true; // 标记为已提供
                    // ... 设置 target, nested exports 等
                  }
                }
              };

              logger.time("figure out provided exports");
              while (queue.length > 0) {
                module = queue.dequeue();
                exportsInfo = moduleGraph.getExportsInfo(module);

                moduleGraph.freeze();
                processDependenciesBlock(module);
                moduleGraph.unfreeze();

                for (const [dep, exportsSpec] of exportsSpecsFromDependencies) {
                  processExportsSpec(dep, exportsSpec);
                }

                modulesToStore.add(module);
              }
              logger.timeEnd("figure out provided exports");

              // ========== Step 3: 存储结果到缓存 ==========
              logger.time("store provided exports into cache");
              asyncLib.each(
                modulesToStore,
                (module, callback) => {
                  const cachedData = moduleGraph
                    .getExportsInfo(module)
                    .getRestoreProvidedData();

                  cache.store(
                    module.identifier(),
                    module.buildInfo.hash,
                    cachedData,
                    callback
                  );
                },
                (err) => {
                  logger.timeEnd("store provided exports into cache");
                  callback(err);
                }
              );
            }
          );
        }
      );
    });
  }
}

export const bar = 'bar';
export const foo = 'foo';
export default 'foo-bar'

// 源码：
export const bar = 'bar';
export const foo = 'foo';
export default 'foo-bar';

// 转换后的 dependencies 数组（简化）：
[
  HarmonyExportSpecifierDependency({ name: 'bar' }),
  HarmonyExportSpecifierDependency({ name: 'foo' }),
  HarmonyExportExpressionDependency({ name: 'default' })
]

// 最终存储到 ModuleGraph.exportsInfo：
{
  'bar': ExportInfo { provided: true, canMangleProvide: true },
  'foo': ExportInfo { provided: true, canMangleProvide: true },
  'default': ExportInfo { provided: true, canMangleProvide: true }
}

// Webpack 5.107
// lib/FlagDependencyUsagePlugin.js
class FlagDependencyUsagePlugin {
  constructor(global) {
    this.global = global; // 是否进行全局分析
  }

  apply(compiler) {
    compiler.hooks.compilation.tap("FlagDependencyUsagePlugin", (compilation) => {
      const moduleGraph = compilation.moduleGraph;

      compilation.hooks.optimizeDependencies.tap(
        { name: "FlagDependencyUsagePlugin", stage: STAGE_DEFAULT },
        (modules) => {
          const logger = compilation.getLogger("webpack.FlagDependencyUsagePlugin");

          /** @type {Map<ExportsInfo, Module>} */
          const exportInfoToModuleMap = new Map();

          /** @type {TupleQueue<Module, RuntimeSpec>} */
          const queue = new TupleQueue();

          /**
           * 处理被引用的模块
           * @param {Module} module - 要处理的模块
           * @param {ReferencedExports} usedExports - 使用的导出列表
           * @param {RuntimeSpec} runtime - 运行时规格
           * @param {boolean} forceSideEffects - 是否强制应用副作用
           */
          const processReferencedModule = (
            module,
            usedExports,
            runtime,
            forceSideEffects
          ) => {
            const exportsInfo = moduleGraph.getExportsInfo(module);

            if (usedExports.length > 0) {
              if (!module.buildMeta || !module.buildMeta.exportsType) {
                // 模块无声明导出信息
                if (exportsInfo.setUsedWithoutInfo(runtime)) {
                  queue.enqueue(module, runtime);
                }
                return;
              }

              for (const usedExportInfo of usedExports) {
                let usedExport;
                let canMangle = true;

                if (Array.isArray(usedExportInfo)) {
                  usedExport = usedExportInfo;
                } else {
                  usedExport = usedExportInfo.name;
                  canMangle = usedExportInfo.canMangle !== false;
                }

                if (usedExport.length === 0) {
                  // 以未知方式使用
                  if (exportsInfo.setUsedInUnknownWay(runtime)) {
                    queue.enqueue(module, runtime);
                  }
                } else {
                  // 遍历导出名路径（支持嵌套导出）
                  let currentExportsInfo = exportsInfo;
                  for (let i = 0; i < usedExport.length; i++) {
                    const exportInfo = currentExportsInfo.getExportInfo(
                      usedExport[i]
                    );

                    if (canMangle === false) {
                      exportInfo.canMangleUse = false;
                    }

                    const lastOne = i === usedExport.length - 1;

                    if (!lastOne) {
                      // 非最后一层：处理嵌套导出
                      const nestedInfo = exportInfo.getNestedExportsInfo();
                      if (nestedInfo) {
                        if (
                          exportInfo.setUsedConditionally(
                            (used) => used === UsageState.Unused,
                            UsageState.OnlyPropertiesUsed,
                            runtime
                          )
                        ) {
                          const currentModule =
                            currentExportsInfo === exportsInfo
                              ? module
                              : exportInfoToModuleMap.get(currentExportsInfo);
                          if (currentModule) {
                            queue.enqueue(currentModule, runtime);
                          }
                        }
                        currentExportsInfo = nestedInfo;
                        continue;
                      }
                    }

                    // 最后一层或无法继续嵌套：标记为 Used
                    if (
                      exportInfo.setUsedConditionally(
                        (v) => v !== UsageState.Used,
                        UsageState.Used,
                        runtime
                      )
                    ) {
                      const currentModule =
                        currentExportsInfo === exportsInfo
                            ? module
                            : exportInfoToModuleMap.get(currentExportsInfo);
                      if (currentModule) {
                        queue.enqueue(currentModule, runtime);
                      }
                    }
                    break;
                  }
                }
              }
            } else {
              // 没有导出被使用（仅因副作用引入）
              if (!forceSideEffects &&
                  module.factoryMeta !== undefined &&
                  module.factoryMeta.sideEffectFree) {
                return; // 无副作用模块，停止追踪
              }

              if (exportsInfo.setUsedForSideEffectsOnly(runtime)) {
                queue.enqueue(module, runtime);
              }
            }
          };

          /**
           * 处理单个模块及其依赖
           */
          const processModule = (module, runtime, forceSideEffects) => {
            /** @type {Map<Module, ReferencedExports | ExportMaps>} */
            const map = new Map();
            /** @type {ArrayQueue<DependenciesBlock>} */
            const blockQueue = new ArrayQueue();
            blockQueue.enqueue(module);

            for (;;) {
              const block = blockQueue.dequeue();
              if (block === undefined) break;

              // 处理异步依赖块
              for (const b of block.blocks) {
                if (b.groupOptions && b.groupOptions.entryOptions) {
                  processModule(
                    b,
                    this.global ? undefined : b.groupOptions.entryOptions.runtime || undefined,
                    true
                  );
                } else {
                  blockQueue.enqueue(b);
                }
              }

              // 处理同步依赖
              for (const dep of block.dependencies) {
                const connection = moduleGraph.getConnection(dep);
                if (!connection || !connection.module) continue;

                const activeState = connection.getActiveState(runtime);
                if (activeState === false) continue;

                const { module: depModule } = connection;

                if (activeState === ModuleGraphConnection.TRANSITIVE_ONLY) {
                  processModule(depModule, runtime, false);
                  continue;
                }

                // 收集被引用的导出
                const oldReferencedExports = map.get(depModule);
                const referencedExports =
                  compilation.getDependencyReferencedExports(dep, runtime);

                // 合并引用信息
                if (oldReferencedExports === undefined ||
                    oldReferencedExports === NO_EXPORTS_REFERENCED ||
                    referencedExports === EXPORTS_OBJECT_REFERENCED) {
                  map.set(depModule, referencedExports);
                } else {
                  // 合并多个引用来源的信息（详见源码 mergeExportsSpec 逻辑）
                }
              }
            }

            // 处理收集到的引用关系
            for (const [depModule, referencedExports] of map) {
              if (Array.isArray(referencedExports)) {
                processReferencedModule(
                  depModule,
                  referencedExports,
                  runtime,
                  forceSideEffects
                );
              } else {
                processReferencedModule(
                  depModule,
                  [...referencedExports.values()],
                  runtime,
                  forceSideEffects
                );
              }
            }
          };

          // ========== 主流程开始 ==========
          logger.time("initialize exports usage");

          // 初始化所有模块的使用状态
          for (const module of modules) {
            const exportsInfo = moduleGraph.getExportsInfo(module);
            exportInfoToModuleMap.set(exportsInfo, module);
            exportsInfo.setHasUseInfo();
          }
          logger.timeEnd("initialize exports usage");

          logger.time("trace exports usage in graph");

          // 从入口模块开始追踪
          const processEntryDependency = (dep, runtime) => {
            const module = moduleGraph.getModule(dep);
            if (module) {
              processReferencedModule(
                module,
                NO_EXPORTS_REFERENCED,
                runtime,
                true
              );
            }
          };

          // 遍历所有入口
          let globalRuntime;
          for (const [
            entryName,
            { dependencies: deps, includeDependencies: includeDeps, options }
          ] of compilation.entries) {
            const runtime = this.global
              ? undefined
              : getEntryRuntime(compilation, entryName, options);

            for (const dep of deps) {
              processEntryDependency(dep, runtime);
            }
            for (const dep of includeDeps) {
              processEntryDependency(dep, runtime);
            }
            globalRuntime = mergeRuntimeOwned(globalRuntime, runtime);
          }

          // 处理全局入口
          for (const dep of compilation.globalEntry.dependencies) {
            processEntryDependency(dep, globalRuntime);
          }
          for (const dep of compilation.globalEntry.includeDependencies) {
            processEntryDependency(dep, globalRuntime);
          }

          // 广度优先遍历处理队列
          while (queue.length) {
            const [module, runtime] = queue.dequeue();
            processModule(module, runtime, false);
          }

          logger.timeEnd("trace exports usage in graph");
        }
      );
    });
  }
}

// index.js
import { bar } from './bar';
console.log(bar);

// bar.js
export const bar = 'bar';
export const foo = 'foo';

// bar.js 打包结果
__webpack_require__.d(__webpack_exports__, {
  "bar": () => /* binding */ bar,  // 保留
  "foo": () => /* binding */ foo    // 保留（即使未使用）
});
const bar = 'bar';
const foo = 'foo';                 // 保留

// bar.js 打包结果
/* unused harmony export foo */     // 标记为未使用
__webpack_require__.d(__webpack_exports__, {
  "bar": () => /* binding */ bar    // 仅保留使用的导出
});
const bar = 'bar';
const foo = 'foo';                 // 定义仍保留（待 Terser 清除）

// Webpack 5.107
// 以 HarmonyExportSpecifierDependency.Template 为例
class HarmonyExportSpecifierDependencyTemplate extends Template {
  apply(dependency, source, templateContext) {
    const dep = dependency;
    const exportsInfo = templateContext.moduleGraph.getExportsInfo(templateContext.module);

    // 读取该导出的使用状态
    const exportInfo = exportsInfo.getExportInfo(dep.name);
    const used = exportInfo.used === UsageState.Used;

    if (used) {
      // ✅ 已使用：生成完整的 __webpack_require__.d 绑定
      source.insert(
        dep.range[0],
        `/* harmony export */ ${templateContext.runtimeTemplate.defineProperty({
          exports: '__webpack_exports__',
          name: JSON.stringify(dep.name),
          value: dep.value || `() => (${dep.name})`
        })}\n`
      );
    } else {
      // ❌ 未使用：添加注释标记，不生成绑定
      source.insert(
        dep.range[0],
        `/* unused harmony export ${dep.name} */\n`
      );
    }
  }
}

// 步骤三生成的代码（标记后）：
/* unused harmony export foo */
__webpack_require__.d(__webpack_exports__, {
  "bar": () => /* binding */ bar
});
const bar = 'bar';
const foo = 'foo';  // ← Dead Code：未被任何地方使用

// 步骤四清除后（Terser DCE）：
__webpack_require__.d(__webpack_exports__, {
  "bar": () => /* binding */ bar
});
const bar = 'bar';
// foo 被完全删除 🗑️

// ❌ v5.105 及之前：无法 Tree Shake
const bar = require('./bar');
// 即使只用到了 bar.foo，整个模块都会被打包

// ✅ v5.106+：支持解构赋值的 Tree Shaking
const { foo } = require('./bar');
// 只有 foo 会被标记为 used，其他导出可以被 Shake 掉

// Webpack 5.106 内部处理（伪代码）
class CommonJSRequireDependencyParser {
  parse(requireCall) {
    if (isDestructuringAssignment(requireCall.parent)) {
      // 识别解构模式
      const destructuredNames = extractDestructuredNames(requireCall.parent);

      // 创建细粒度的引用信息
      return {
        type: 'CommonJSDestructure',
        referencedExports: destructuredNames.map(name => ([name]))
        // 例如：[['foo']] 表示只使用了 foo
      };
    }
    // 非解构：整模块引用
    return {
      type: 'CommonJSRequire',
      referencedExports: EXPORTS_OBJECT_REFERENCED
    };
  }
}

// library.js (CommonJS)
module.exports = {
  foo: 'foo',
  bar: 'bar',
  baz: function() { /* ... */ }
};

// consumer.js
const { foo } = require('./library');
console.log(foo);

// 打包结果（v5.106+）：
// ✅ 只包含 foo 的定义
// ❌ bar 和 baz 被移除（如果没有副作用）

// ✅ v5.107+：支持 #__NO_SIDE_EFFECTS__ 注解
// 注意：注解是位于函数声明【之前】的块注释，不能写在函数体内
/*#__NO_SIDE_EFFECTS__*/
function pureFunction() {
  return computeSomething();
}

// 调用时无需额外注解
pureFunction(); // ← 自动识别为无副作用，可被 Tree Shaking

// utils.js
/*#__NO_SIDE_EFFECTS__*/
function helper() {
  const result = expensiveComputation();
  return result;
}

// consumer.js
import { helper } from './utils';

helper(); // ✅ 自动识别为无副作用
helper(); // ✅ 同样自动识别
helper(); // ✅ 无需重复标注

// 如果 helper 未被使用，整个函数定义都会被移除

// Webpack 5.107 SideEffectsFlagPlugin（简化）
// 真实实现：通过 parser.hooks.preStatement 检测函数声明【前】的注释
parser.hooks.preStatement.tap(PLUGIN_NAME, (statement) => {
  // 仅检测顶层 function 声明：
  //   1. function foo  2. export function foo  3. export default function foo
  if (statement.type !== "FunctionDeclaration" || !statement.id) return;

  // 扫描上一条语句结束到函数声明开始之间的注释
  if (hasNoSideEffectsNotation(parser, commentsStart, statement.range[0])) {
    noSideEffectsFnNames.add(statement.id.name); // 记录为无副作用函数
  }
});

// 另通过 parser.hooks.preDeclarator 检测 const fn = /*#__NO_SIDE_EFFECTS__*/ (...) 形式
// 后续：调用这些函数的 CallExpression 自动视为 pure，无需逐个标注

// ❌ v5.106 及之前的问题
[
  /*#__PURE__*/ foo(),
  bar() // ← 这个也可能被错误地视为 pure
]

// ✅ v5.107 修复后
[
  /*#__PURE__*/ foo(), // 只影响 foo()
  bar() // 正确识别：不受 foo() 的 PURE 注解影响
]

// ✅ v5.107+ 支持
const message = `hello ${/*#__PURE__*/ getName()} world`;
// getName() 被正确识别为纯调用

// a.js
export const x = 1;
export const y = 2;

// b.js
export { x } from './a';

// c.js (entry)
import { x } from './b';
console.log(x);

// Scope Hoisting + Tree Shaking 后的结果：
// ✅ 直接内联，无需中间模块包装
(() => {
  const x = 1; // 来自 a.js
  console.log(x); // y 被完全消除
})();

{
  "name": "my-library",
  "version": "1.0.0",
  "sideEffects": false
}

{ "sideEffects": ["*.css", "*.scss"] }

{ "sideEffects": "./src/side-effectful-file.js" }

// FlagDependencyUsagePlugin 中的关键逻辑
if (!forceSideEffects &&
    module.factoryMeta !== undefined &&
    module.factoryMeta.sideEffectFree) {
  // 如果模块无副作用且没有任何导出被使用
  // 则完全跳过该模块，不将其加入 bundle
  return;
}

// 对于纯工具库（推荐）
{
  "name": "utils-lib",
  "sideEffects": false
}

// 对于包含 CSS 的 UI 库
{
  "name": "ui-components",
  "sideEffects": ["*.css", "*.less", "*.scss"]
}

// 对于有特定副作用文件的库
{
  "name": "plugin-system",
  "sideEffects": ["./src/register.js", "./src/setup.js"]
}

// ✅ 推荐：ESM（静态可分析）
export const bar = 'bar';
export const foo = 'foo';

// ❌ 避免：CommonJS（动态难以预测）
if (process.env.NODE_ENV === 'development') {
  exports.foo = 'foo'; // 条件导出，无法静态分析
}

// ❌ 问题代码
import { bar, foo } from "./bar";
let f = foo; // foo 被赋值给 f，但 f 也未被使用
// 结果：foo 无法被 Tree Shaking

// ✅ 优化方案：直接使用需要的导出
import { bar } from "./bar";
console.log(bar);

// 标注单次调用
/*#__PURE__*/ foo('be retained');
/*#__PURE__*/ foo('be removed'); // 可被 Tree Shaking

// 标注函数本身（所有调用点自动生效）
// 仅支持顶层 function 声明与 const fn = 函数表达式 两种形式
/*#__NO_SIDE_EFFECTS__*/
function processData() {
  return transform(data);
}

processData(); // ✅ 自动识别为 pure
processData(); // ✅ 无需重复标注

// babel.config.js（错误配置）
module.exports = {
  presets: [
    ['@babel/preset-env', {
      modules: 'commonjs' // ❌ 导致 Tree Shaking 失效
    }]
  ]
};

// babel.config.js（正确配置）
module.exports = {
  presets: [
    ['@babel/preset-env', {
      modules: false // ✅ 保持 ESM，允许 Tree Shaking
    }]
  ]
};

// webpack.config.js
module.exports = {
  module: {
    rules: [{
      test: /\.js$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: [
            ['@babel/preset-env', {
              modules: false // 关键！
            }]
          ]
        }
      }
    }]
  }
};

// ❌ 粒度过粗
export default {
  bar: 'bar',
  foo: 'foo',
  // ... 很多属性
};

// ✅ 粒度细化
const bar = 'bar';
const foo = 'foo';

export { bar, foo }; // 可以单独 shake 每个

// 声明将要消费的异步模块导出
import(
  /* webpackExports: ["foo", "default"] */
  "./foo"
).then((module) => {
  console.log(module.foo); // 只加载和使用 foo
});

// 或使用魔法注释组合
import(
  /* webpackChunkName: "async-foo" */
  /* webpackExports: ["bar"] */
  './foo'
).then(({ bar }) => {
  console.log(bar);
});

// package.json
{
  "name": "my-package",
  "sideEffects": [
    "*.css",
    "*.scss",
    "./src/register-plugin.ts",
    "./dist/polyfill.js"
  ]
}