在 package.json 中配置 sideeffects 字段，可以明确告知打包工具哪些文件包含副作用。如果设置为 false，表示所有模块都是纯函数式的，没有副作用；如果设置为数组，则列出具体包含副作用的文件路径（如 css 或全局脚本）。这样配置后，tree shaking 能够安全地移除未使用的代码，从而减小最终打包文件的体积。
如何配置 sideEffects 为 false 以启用最大程度的 Tree Shaking
将 sideEffects 设置为布尔值 false 是最简单的配置方式，它告诉 Webpack、Rollup 等构建工具，当前包内的所有 JavaScript 模块都不会产生副作用。这意味着只要某个模块没有被导入或使用，就可以被安全地丢弃。这种配置适用于那些完全由纯函数组成、不修改全局环境、不注入样式的库。开发者只需在 package.json 根目录下添加一行 "sideEffects": false 即可生效。
{
"name": "my-pure-lib",
"version": "1.0.0",
"description": "A library with no side effects",
"main": "index.js",
"sideEffects": false
}
当 sideEffects 为 false 时，即使你的 index.js 导入了一个内部工具函数，如果该工具函数在你的业务代码中从未被调用，打包工具也会将其从最终的 bundle 中剔除。这要求开发者确保自己的代码确实没有任何隐式副作用，例如不要在模块顶层直接执行 DOM 操作或注册全局事件监听器。
立即学习“Java免费学习笔记（深入）”；
你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型
如何配置 sideEffects 为数组以保留特定副作用文件
在实际项目中，很多库需要引入 CSS 文件或执行一些一次性初始化脚本，这些都属于副作用。此时不能简单地将 sideEffects 设为 false，而应该将其配置为一个字符串数组，明确列出哪些文件包含副作用。构建工具会保留这些列出的文件，即使它们未被显式导入，同时仍然可以对其他未列出的 JS 模块进行 Tree Shaking。常见的副作用文件包括 *.css、*.scss 或特定的入口脚本。
{
"name": "my-ui-kit",
"version": "1.0.0",
"main": "dist/index.js",
"sideEffects": [
"*.css",
"src/polyfill.js"
]
}
在上述示例中，*.css 通配符表示所有 CSS 文件都会被保留，因为样式表通常需要通过 import 加载才能生效，且其内容不应被随意删除。而 src/polyfill.js 是一个具体的文件，它可能在模块加载时自动修补浏览器兼容性。通过这种方式，既保证了功能的完整性，又最大化了代码的优化空间。
sideEffects 配置对未使用模块删除的具体影响
为了验证 sideEffects 的实际效果，我们可以看一个具体的例子。假设有一个库 utils.js，其中定义了一个函数 formatDate 和一个全局变量赋值 window.myGlobal = true。如果 sideEffects 配置正确，打包工具的行为会有显著差异。当 sideEffects 为 false 时，由于存在全局变量赋值这一副作用，理论上所有模块都应被视为有副作用，但配置本身是开发者的声明，若开发者误标为 false，可能导致运行时错误。更准确的情况是，如果 sideEffects 数组中不包含 utils.js，且该文件未被导入，它将被移除。如果它被导入但未使用其中的函数，函数会被移除，但若文件本身被标记为有副作用，整个文件可能不会被 Tree Shaking 掉，除非工具支持模块级副作用分析。
// utils.js
export function formatDate(date) {
return date.toISOString();
}
// 这是一个副作用
window.myGlobal = 'initialized';
// main.js
import { formatDate } from 'my-lib/utils';
console.log(formatDate(new Date()));
在这个场景中，如果 package.json 中的 sideEffects 数组包含了 utils.js，那么即使 formatDate 是唯一使用的导出，整个 utils.js 文件也会被包含在 bundle 中，以确保 window.myGlobal 被正确设置。反之，如果 sideEffects 不包含 utils.js，且工具足够智能，它可能会只保留 formatDate 函数，而丢弃全局赋值部分，但这取决于具体打包工具的实现。通常情况下，为了安全起见，应将包含副作用的文件明确列入数组。
