在 package.json 中配置 sideeffects 字段,可以告诉打包工具哪些文件包含副作用。如果设为 false,表示所有模块都是纯函数式的,可以进行 tree shaking;如果设为数组,则列出包含副作用的文件路径(如 ["*.css"]),这些文件不会被移除。这样能显著减小最终打包体积。

如何配置 sideEffects 为 false 以启用全局 Tree Shaking
当你的项目完全由纯 ES Module 组成且没有任何全局副作用时,可以将 sideEffects 设置为 false。这允许 Webpack、Vite 或 Rollup 等工具安全地删除未使用的导出代码。

{
"name": "my-pure-lib",
"version": "1.0.0",
"sideEffects": false,
"main": "dist/index.js",
"module": "src/index.js"
}
上述配置表明该库的所有 JS 文件都是无副作用的。只要确保导入的代码不修改全局原型链、不注入全局变量即可。例如,一个只包含纯函数的工具库:
// src/utils.js
export const add = (a, b) => a + b;
// src/index.js
export { add } from './utils';
运行构建后,如果消费者只使用了 add,其他未导出的函数将被彻底移除。
如何处理包含 CSS 或全局脚本的 sideEffects
许多库需要引入 CSS 文件或执行全局初始化代码,这些操作具有副作用,不能被 Tree Shaking 删除。此时需要在 sideEffects 数组中明确声明这些文件。
FilePond 是一个 JavaScript 文件上传库,支持通过拖拽、粘贴和 API 方式处理文件、目录、URL 和 Data URI。它包含内置的图像优化功能、异步分块上传功能,并提供了适用于 React、Vue、Angular 和 Svelte 的适配器。

{
"name": "my-ui-kit",
"version": "1.0.0",
"sideEffects": [
"*.css",
"src/polyfill.js"
],
"main": "dist/index.js",
"module": "src/index.js"
}
在这个例子中,*.css 匹配所有 CSS 文件,src/polyfill.js 是特定的全局脚本。即使某个 CSS 文件未被任何组件直接 import,只要它被库的其他部分间接依赖或作为入口引入,它也会被保留。而其他的 JS 模块如果没有被使用,依然会被优化掉。
sideEffects 配置对未使用模块的具体影响
通过对比不同配置下的打包结果,可以清晰看到 sideEffects 的作用机制。以下是一个简单的验证场景:一个库包含三个模块,其中两个有副作用,一个是纯函数。
// package.json
{
"sideEffects": ["*.css", "global.js"]
}
// global.js (有副作用)
console.log('Global init');
// pure.js (无副作用)
export const util = () => 'pure';
// unused.js (无副作用,但未使用)
export const deadCode = () => 'dead';
当用户仅导入 util 时:
-
global.js会被保留,因为它在sideEffects列表中。 -
pure.js会被保留,因为它是被引用的。 -
unused.js会被移除,因为它既未被引用,也不在sideEffects列表中。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南










