Pulverize Universe 并不是 Webpack 官方文档中的单个 API，而是社区对 Webpack 5 中一组极致摇树优化能力的形象概括。它的核心思想是把模块依赖关系看作一个宇宙，每一个未被直接或间接使用到的模块、导出、函数片段都是漂浮的星尘，最终通过构建期的静态分析被粉碎并从产物中移除。这个思路依赖 Webpack 5 对 ESM 严格静态结构的支持，以及 sideEffects、usedExports、concatenateModules 等配置的协同工作。下面拆解这套机制的实际原理与落地方法。
理解 Pulverize Universe：它到底粉碎了什么
Webpack 在编译阶段会生成一张模块依赖图，每个模块都带有 exports 和 imports 信息。如果某个模块被 import，但它的导出并没有全部被使用，传统构建工具往往仍会把整个模块保留下来。Webpack 5 通过分析 ESM 的静态 import 与 export 语法，可以识别出哪些导出真正被消费。那些未被消费的导出就是粉碎宇宙要清理的第一类对象。
这种清理并不是简单地在压缩阶段删除函数。Webpack 5 会在编译阶段给导出项打上 used 标记，然后交给 Terser 等压缩工具进行实际删除。配合 concatenateModules，多个模块还会被合并成同一个作用域，原本跨模块的函数调用会变成直接调用，JavaScript 引擎和压缩工具都能更容易发现不可达代码。最终效果就是：不仅整个模块可能消失，模块内部的未使用函数、未引用的变量声明、条件分支中的死代码都会被一层层剥离。
可以把粉碎过程分成三个层级。第一层是模块级粉碎，由 sideEffects 控制，直接移除无副作用且未被引用的模块。第二层是导出级粉碎，由 usedExports 控制，只保留模块中被外部真正用到的导出项。第三层是作用域级粉碎，由 concatenateModules 控制，合并模块作用域后进一步暴露不可达代码。三个层级叠加后，构建产物会明显缩小。以下配置展示了生产模式下如何开启这些能力。
// webpack.config.js
module.exports = {
mode: 'production',
optimization: {
usedExports: true,
concatenateModules: true,
sideEffects: true,
minimize: true,
splitChunks: {
chunks: 'all',
minSize: 0
}
}
};
sideEffects 配置：粉碎宇宙的关键开关
sideEffects 是定义在 package.json 中的一个字段。它告诉 Webpack 哪些文件没有副作用，可以被安全地删除。Webpack 5 默认会在生产模式下识别这个字段。把它设置为 false，意味着整个包中的所有模块都可以被无条件移除，只要它们没有被其他模块引用。这对纯函数库非常有用，例如日期处理、数学计算、工具函数等库，通常可以在声明 sideEffects: false 后获得更小的体积。
但 sideEffects 并不总是安全的。很多模块在顶层执行时就产生了副作用，例如注册 Web Components、写入全局变量、初始化 polyfill、导入 CSS 文件等。如果这些文件被错误地标记为无副作用，Webpack 就会在打包时将它们移除，导致运行时报错。一个常见的做法是使用数组形式，只列出真正具有副作用的文件，例如：
{
"name": "pulverize-universe-demo",
"sideEffects": [
"*.css",
"src/polyfills.js"
]
}
实际项目中，建议不要在根目录 package.json 里直接粗暴地设置 sideEffects: false，除非你非常清楚每一个依赖的行为。可以先使用 sideEffects 数组标记样式文件和 polyfill，再结合 usedExports 分析导出项。这样既能保留必要的副作用，又能让 Webpack 5 在其他模块上放心地执行模块级粉碎。可以用 stats 查看最终有哪些模块因 sideEffects 被移除，便于验证配置是否正确。
模块联邦与 splitChunks 如何参与代码粉碎
Pulverize Universe 在模块联邦场景下尤为重要。Webpack 5 的模块联邦允许一个应用在运行时加载另一个应用暴露的模块，但远程模块往往暴露大量导出，而消费方可能只需要其中一个小功能。如果没有有效的树摇，远程入口会包含大量未使用的代码。Webpack 5 在远程模块加载时同样会遵循 usedExports 和 sideEffects 的标记，将未使用的导出项排除在最终 chunk 之外。
另一方面，splitChunks 的作用并不是删除代码，而是把公共依赖切割成独立的缓存块。代码粉碎需要与代码分割配合，避免因为分割过度产生大量小文件，也避免因为不分割导致一个巨大的 chunk 中包含了本可以移除的半使用依赖。一个合理的 splitChunks 配置可以把 node_modules 中的第三方库单独拆出，让浏览器缓存的效率更高。以下是一个常见的缓存组配置：
optimization: {
splitChunks: {
cacheGroups: {
vendors: {
test: /[\\/]node_modules[\\/]/,
name: 'vendors',
chunks: 'all'
}
}
}
}
当模块联邦与 splitChunks 同时使用时，共享依赖的版本管理与去重会变得更加复杂。Webpack 5 的 ModuleFederationPlugin 支持 shared 配置，把 react、react-dom 等库声明为共享依赖。宿主和远程应用会优先使用共享实例，而不是各自打包一份。这样不仅减少了重复代码，也让粉碎宇宙可以更集中地处理业务代码中的未使用导出，避免在多个远程包里反复出现同一段死代码。
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'host',
remotes: {
remoteApp: 'remoteApp@http://localhost:3001/remoteEntry.js'
},
shared: ['react', 'react-dom']
})
]
};
避坑指南：如何防止粉碎宇宙误删必要代码
粉碎式优化最怕的是误删副作用代码。一个典型的翻车场景是：把 sideEffects 设为 false 后，打包看似成功，但应用在浏览器里加载样式丢失，或者某个全局变量突然变成 undefined。这类问题在开发阶段不容易发现，往往要等到生产环境运行时才暴露。
要避免这类问题，首先需要确认项目中是否包含 CSS、less、scss 文件。样式文件具有副作用，它们被 import 是为了让构建工具将样式提取到单独文件中。如果 sideEffects 设置不正确，样式导入会被当成无副作用而直接移除。正确的做法是把所有样式后缀写入 sideEffects 数组，例如 "*.css"、 "*.less"。对于 polyfill 和注册类代码，也要单独列出具体路径。
其次可以利用 Webpack 的 stats 调试信息。在 webpack.config.js 中设置 stats 的 orphanModules、usedExports、reasons 等选项，可以输出模块被移除的原因和导出使用情况。如果发现某个模块被错误移除，可以查看它是否被标记为无副作用，或者是否所有导出都被认为未使用。根据这些信息调整 sideEffects 或代码中的导出方式即可。以下是一个调试配置示例：
// webpack.config.js 输出更详细的构建日志
module.exports = {
stats: {
orphanModules: true,
usedExports: true,
providedExports: true,
reasons: true
}
};
另外，如果项目使用了 TypeScript 或 Babel，还需要确保它们没有破坏 ESM 语义。比如 Babel 的 commonjs 转换会把 import 变成 require，这会使得 Webpack 无法进行静态分析，粉碎宇宙基本失效。应该使用 babel-preset-env 的 modules: false 或者使用 @babel/preset-env 配合 caller 支持，让 ESM 语法保留给 Webpack 处理。只有这样，usedExports 和 sideEffects 才能真正生效。
Pulverize Universe 不是某个独立开关，而是 Webpack 5 多种编译优化机制的组合效果。理解 sideEffects、usedExports、concatenateModules、splitChunks 以及模块联邦之间的关系，才能安全地实现极致代码消除。建议在实际项目中逐步开启这些能力，并通过构建产物分析和运行测试来验证效果。当配置得当时，你会发现打包结果中真正剩下的代码，几乎全部是应用运行所必需的逻辑，那些曾经占据体积的宇宙尘埃已经被彻底粉碎。
Webpack 5Pulverize Universe粉碎宇宙修改时间：2026-08-26 05:11:48