Webpack 的 optimization.usedExports 是如何标记未使用导出的？深入理解 Tree Shaking 机制

Webpack 打包时明明引入的库只用了两个函数，产物里却塞进了整个模块，这类问题几乎都和 optimization.usedExports 的行为有关。这个配置项决定了 Webpack 是否会在编译阶段分析每个模块的导出项，并把从未被引用的导出标记为未使用，为后续的压缩删除提供依据。理解它的工作原理，是掌握 Tree Shaking 的第一步。

usedExports 到底做了什么

先看最基本的配置。在 mode: 'production' 下，Webpack 默认开启了 optimization.usedExports: true，如果是开发环境或手动配置，可以这样显式开启：

module.exports = {
  mode: 'production',
  optimization: {
    usedExports: true,
    minimize: true,
    minimizer: [
      new (require('terser-webpack-plugin'))({
        terserOptions: {
          compress: { dead_code: true },
          mangle: true,
        },
      }),
    ],
  },
};

需要明确一点：usedExports 本身并不会删除任何代码。它做的事情是静态分析——遍历模块的导出语句，统计哪些导出被其他模块通过 import 实际引用了，然后在产物中给未使用的导出加上注释标记，例如 /* unused harmony export square */。真正把这些死代码从产物里删掉的，是 Terser 等压缩工具在 minimize 阶段根据这些标记完成的。

这也是为什么很多人开了 usedExports 却没看到体积变化——如果 minimize 被关闭，或者压缩器没有正确识别标记，未使用的导出依然会留在产物里。可以用 optimization.usedExports 配合 stats: { optimizationBailout: true } 查看 Webpack 给出的分析提示，定位哪些模块无法被标记。

为什么必须基于 ES Module 静态结构

usedExports 的分析能力完全依赖 import 和 export 语法的静态特性。ES Module 的导入导出关系在代码解析阶段就能确定，Webpack 不需要执行代码就能构建出完整的依赖图谱，从而精确知道某个函数有没有被外部引用。来看一个例子：

// math.js
export function add(a, b) {
  return a + b;
}
export function square(x) {
  return x * x;
}

// main.js
import { add } from './math.js';
console.log(add(1, 2));

开启 usedExports 后，Webpack 会发现 square 从未被引用，于是在打包产物里它会被标记为 unused harmony export，压缩阶段直接删除。最终产物中只保留 add 的实现。

如果换成 CommonJS，情况就完全不同了：

// math.js
exports.add = function (a, b) { return a + b; };
exports.square = function (x) { return x * x; };

// main.js
const math = require('./math');
console.log(math.add(1, 2));

require 是运行时行为，模块对象的属性可以在任何地方动态挂载和访问，Webpack 无法静态证明 math.square 一定不会被用到，所以只能保守地把两个函数都保留。这就是为什么同样一份工具库，ESM 版本可以摇掉大部分代码，而 CJS 版本不行。引入第三方库时应尽量选择提供 ESM 入口的版本，并确认 package.json 的 module 或 exports 字段指向 ESM 产物。

sideEffects 与 usedExports 的协作关系

这两个配置经常被混淆。usedExports 处理的是模块内部未使用的导出，而 sideEffects 决定的是整个模块是否可以被跳过。假设有这样的入口：

// main.js
import { Button } from './ui';
console.log(new Button());
// main.js 中没有 import './polyfill'，但被其他文件间接引入

// polyfill.js
import './extend-string'; // 无导出，只有副作用
if (!String.prototype.padStart) {
  String.prototype.padStart = function () { /* ... */ };
}

polyfill.js 没有任何导出，但它修改了原生原型，属于有副作用的模块。如果 package.json 里声明了 "sideEffects": false，Webpack 会认为整个文件都可以安全跳过，polyfill 就丢了，运行时报错。正确的做法是在 package.json 中精确声明：

{
  "sideEffects": false,
  "sideEffects": ["./src/polyfill.js", "*.css"]
}

注意上面示例只是为了对比，实际项目中两个字段只能保留一个。当模块被声明为无副作用且未被引用时，Webpack 连解析它都不需要，效果比 usedExports 更彻底；而 usedExports 是模块一定被打包时，对内部导出做精细化裁剪。两者配合使用，才能达到最优的摇树效果。

验证标记效果与常见踩坑点

验证方式很直接：构建后用文本编辑器搜索未压缩产物中的 unused harmony export 注释，确认标记是否生效；再对比压缩产物的体积，确认删除是否执行。也可以在配置中临时加一个分析插件，输出每个模块的导出使用情况。

几个常见的坑值得留意。第一，动态访问会破坏分析，比如 import * as utils from './utils' 之后通过 utils[name] 取值，Webpack 无法静态确定用了哪个导出，整个模块的导出全部保留。第二，export default 的对象整体导出会连带保留所有属性，推荐拆成多个具名导出，让每个函数可被独立标记。第三，Babel 配置不当会把 ESM 提前转成 CJS，导致分析失效，需检查 @babel/preset-env 的 modules 选项是否设置为 false，把模块转换留给 Webpack 处理。

总结来看，optimization.usedExports 是 Tree Shaking 链条中的分析环节，它依赖 ESM 静态结构完成未使用导出的标记，再交给压缩器执行删除。写出可被静态分析的代码——具名导出、避免动态访问、正确声明副作用——才能让这套机制发挥最大价值。

WebpackusedExportsTree Shaking修改时间：2026-09-07 17:48:39