Webpack未摇树优化：导入单个库导出却打包整个库问题排查

这问题我之前帮不少开发者排查过，核心原因大概率是你的库入口文件的导出方式、模块类型或者配置不符合Webpack摇树优化的要求，咱们一步步拆解：

1. 先确认模块类型是否为ES模块（ESM） #

Webpack的Tree Shaking只对ES模块（用import/export语法）生效，如果你的库内部混用了CommonJS（require/module.exports），哪怕入口文件用export导出，Webpack也没法精准识别哪些代码未被使用。

举个反例：如果你的库内部是这样写的，摇树肯定失效：

// 库内部文件a.js
module.exports = function A() {};

// 入口index.js
const A = require('./a');
const B = require('./b');
export { A, B };

这种混合写法会让Webpack把整个模块标记为不可拆分，最终打包整个库。

2. 检查入口文件的导出写法 #

如果你的入口文件是把所有导出合并成一个对象再导出，比如：

import * as allModules from './allModules';
export default allModules;

或者直接导出一个包含所有成员的对象，Webpack无法拆分单个导出的依赖关系，自然没法摇树。

正确的写法应该是逐个导出：

export { A } from './a';
export { B } from './b';
// ... 对应每个模块的单独导出

这种方式Webpack能清晰识别每个导出的来源，方便后续摇树。

3. 关键：配置sideEffects字段 #

Webpack默认会假设所有模块都有副作用（比如修改全局变量、操作DOM的代码），所以即使你没用到某些导出，它也不敢随意删除。你需要在库的package.json里明确声明是否有副作用：

• 如果库所有文件都没有副作用（纯函数/纯数据导出），直接加：

  "sideEffects": false
  

• 如果有部分文件确实有副作用（比如全局样式、初始化代码），就列出具体文件：

  "sideEffects": ["./src/styles.css", "./src/init.js"]
  

这一步是很多摇树失效的核心原因，千万别忽略！

4. 检查Webpack生产模式配置 #

webpack -p其实对应Webpack的mode: 'production'，这个模式下默认开启摇树，但如果你的配置里手动关闭了相关选项，也会导致失效：

• 确保optimization.usedExports设为true（生产模式默认开启）：这个选项让Webpack标记出未使用的导出
• 确保optimization.minimize设为true（生产模式默认开启）：配合TerserPlugin（Webpack 4+默认）来删除标记的未使用代码

另外，非生产模式下（直接跑webpack），Webpack只会输出unused harmony export的提示，不会实际删除代码——因为开发模式要保留完整代码方便调试，只有生产模式下才会执行真正的摇树删除。

总结排查步骤 #

1. 确保库的所有模块都使用ES模块语法，无CommonJS混用
2. 入口文件采用逐个导出的方式，避免导出整体对象
3. 在库的package.json中正确配置sideEffects字段
4. 确认Webpack生产模式下的优化选项未被手动关闭

内容的提问来源于stack exchange，提问作者Paul T.