sideeffects是package.json中用于声明模块副作用的白名单字段：设为false表示全包无副作用可安全摇树，true表示全包有副作用禁用摇树，数组则仅列出有副作用的文件路径或glob模式（如"*.css"），未列出者默认可移除。
在 JavaScript 项目中，sideEffects 是 package.json 中一个用于告知打包工具（如 Webpack、Rollup）哪些模块**可以安全地被摇树（tree-shake）** 的字段。它不标记“无副作用代码”，而是明确告诉打包器：**哪些文件或模式是“有副作用”的**；其余未列出的文件，默认视为“无副作用”，可被移除。
sideEffects 的作用逻辑
它本质是一个白名单机制：
- 如果设为
false：整个包被视为无副作用，所有未被引用的导出（包括默认导出、命名导出）都可被删除。 - 如果设为
true：整个包被视为有副作用，禁止任何摇树（等价于关闭 tree-shaking）。 - 如果设为字符串数组（最常用）：仅数组中列出的路径或 glob 模式对应文件被视为有副作用；其他文件即使没被引用，也可安全移除。
常见 sideEffects 数组写法
典型值示例（适用于大多数纯函数库）：
"sideEffects": [ "./src/styles.css", "./dist/*.css", "*.d.ts", "*.json" ]
说明：
-
"./src/styles.css"：明确 CSS 文件有副作用（执行即注入样式），不能删。 -
"*.d.ts"：类型声明文件不影响运行时，但需保留供 TS 使用；实际打包时不会被包含，写在这里只是惯例，不影响行为。 -
"*.json"：JSON 导入可能触发副作用（如读取配置、影响环境），保守起见常列入。 -
"./dist/*.css"：若构建产物含 CSS，也需声明，避免被误删。
必须注意的关键细节
sideEffects 只对 **ES 模块（ESM）导入/导出** 生效；CommonJS（require）不受影响。
- 确保你的包发布的是 ESM 格式（
"type": "module"或"exports"字段正确配置）。 - 入口文件（如
index.js）若本身执行了副作用（如修改全局对象、注册插件、发起请求），就必须出现在sideEffects列表中，否则会被删掉。 - 数组中的路径是相对于
package.json的位置，支持 glob（如"src/**/*.css"），但不支持正则表达式。 - Webpack 5+ 默认启用此字段；Rollup 需配合
treeshake: { moduleSideEffects: 'no' }等配置才能完全尊重它。
验证是否生效的小技巧
快速检查 tree-shaking 是否按预期工作：
- 在项目中只 import 一个函数：
import { foo } from 'your-lib'； - 构建后查看打包产物（如 dist/main.js），搜索未用到的导出（如
bar）是否还存在； - 若存在，检查该导出所在文件是否被
sideEffects错误包含，或该文件本身有隐式副作用（如顶层console.log、localStorage.setItem）。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
