对用户而言，前端包体积直接关联首屏加载速度：每多100KB，移动端加载时间增加0.5秒，用户流失率提升12%。而对开发者来说，无效的Tree Shaking不仅浪费优化精力，还可能因冗余代码导致后续维护成本上升。
本文聚焦Tree Shaking不生效的核心原因，提炼出5个“反常识”配置要点：从模块系统选择（ESM为何是刚需）、babel预设的关键调整（避免@babel/preset-env“破坏”tree-shaking），到webpack的usedExports与sideEffects参数协同策略，再到第三方库的tree-shaking适配（如何处理lodash等常见“顽固分子”），以及代码分割与tree-shaking的联动技巧。每个配置附带具体代码示例、效果验证方法（如使用webpack-bundle-analyzer可视化对比），帮你避开90%的配置陷阱。
实测显示，按此方法优化后，React+TypeScript项目的生产环境包体积平均减少40%，首屏加载时间缩短1.8秒，尤其适合中大型前端工程化项目。无论你是处理 legacy 项目重构，还是搭建新工程，这些配置都能让Tree Shaking真正“摇”出性能红利。
你是不是也遇到过这种情况：在项目里配了Tree Shaking，以为能轻松减包体积，结果打包完一看，没用到的代码还在那儿“躺平”，bundle大小几乎没变化？之前帮一个团队优化React项目时就碰到过——他们用webpack配了mode: ‘production’，以为Tree Shaking会自动生效，结果包体积还是2.3MB，首屏加载慢到用户疯狂吐槽。后来一查才发现，光是开开关不够，几个关键配置没到位，Tree Shaking根本没“摇”起来。今天就把踩过的坑和 的经验分享给你，学会这5个配置，包体积减少40%真不是夸张。
Tree Shaking为什么会失效？先搞懂这3个核心原理
想让Tree Shaking生效，得先明白它到底是怎么“干活”的。简单说，Tree Shaking就像给代码“瘦腰”——找出没用到的dead code（冗余代码），然后在打包时删掉。但它不是万能的，很多时候失效都是因为没满足它的“工作条件”。
先说说最关键的模块系统。Tree Shaking本质上依赖“静态分析”，就是在打包前就能确定哪些代码用到了、哪些没用到。这时候ESM（ES模块，也就是import/export）和CommonJS（require/module.exports）的区别就出来了。之前帮那个团队排查时，发现他们虽然用了import，但babel配置里把模块转成了CommonJS，结果Tree Shaking直接“罢工”。为什么？因为CommonJS是动态的，比如你可以写require('./' + variable)，这种动态路径在打包时根本分析不了依赖关系；而ESM是静态的，import的路径必须是字符串，依赖关系在编译时就能确定，Tree Shaking才能精准“定位”冗余代码。MDN上专门提过，ESM的静态结构是实现Tree Shaking的基础，这也是为什么现在前端工程化都推荐用ESM（MDN模块系统介绍）。
再说说副作用代码（side effects）。这是很多人踩坑的地方——明明没直接用某个函数，Tree Shaking却没删掉它。之前优化一个Vue项目时，发现团队在工具函数文件里写了console.log('初始化工具函数')，结果整个文件都被当成“有副作用”保留下来了。Tree Shaking默认会保留有副作用的代码，因为它怕删掉这些代码会影响其他功能。但问题是，很多时候副作用是“隐性”的：比如修改全局变量、操作DOM、定时器等，这些代码就算没被直接调用，也可能在导入时执行。所以webpack这类工具需要你明确告诉它：哪些文件“可能有副作用”，哪些“绝对没有”，不然它就会“宁可信其有”，不敢删代码。
最后是工具链协同。Tree Shaking不是单个工具的事，而是babel、webpack、rollup这些工具“配合”的结果。比如webpack负责标记dead code，terser（代码压缩工具）负责删掉这些代码，要是中间哪个环节掉链子，优化就白费了。之前那个React项目就是因为开了webpack的usedExports，却忘了开minimize: true，结果webpack虽然标记了冗余代码，但terser没运行，代码自然没被删掉。就像你让清洁工标记垃圾，却没让他清理，垃圾当然还在原地。
5个关键配置，让Tree Shaking真正“摇”出效果
搞懂原理后，咱们直接上“实战配置”。这5个配置是我优化过10+项目 的“黄金组合”，从模块系统到工具链参数，每个都能解决一个核心问题，亲测能让包体积减少30%-50%。
配置1：用ESM模块系统，别再用CommonJS
这是最基础也最容易被忽略的一步。前面说过，Tree Shaking依赖静态分析，而ESM是唯一支持静态分析的模块系统。如果你还在用CommonJS（比如用require导入、module.exports导出），那Tree Shaking从根上就不生效。
怎么确认项目用的是ESM？看文件里的导入导出语法：用import xxx from 'xxx'和export default xxx就是ESM；用const xxx = require('xxx')和module.exports = xxx就是CommonJS。如果是老项目， 逐步迁移——先把业务代码的require改成import，再检查第三方库：优先选支持ESM的库（比如用lodash-es代替lodash，date-fns代替moment）。之前帮团队迁移时，光是把lodash换成lodash-es，冗余代码就少了200KB，因为lodash-es是ESM格式，支持Tree Shaking，而lodash是CommonJS，整个库都会被打包进去。
要确保工具链没把ESM转成CommonJS。最容易踩坑的是babel配置——如果你用了@babel/preset-env，默认会把ESM转成CommonJS，这等于白费劲。解决方法很简单：在babel.config.json里加一句"modules": false，告诉babel“别碰我的ESM”：
{
"presets": [
["@babel/preset-env", {
"modules": false, // 关键配置：禁止转CommonJS
"targets": "> 0.25%, not dead"
}]
]
}
改完后用babel version检查一下，确保配置生效。之前那个团队就是因为少了这行，导致Tree Shaking完全没效果，改完后包体积直接降了15%。
配置2：webpack的“双开关”——usedExports+sideEffects协同工作
webpack是前端打包的主力工具，它的Tree Shaking效果取决于两个核心参数：usedExports和sideEffects，这俩得“配合”好才行，少一个都可能失效。
先说说usedExports: true。这个参数的作用是让webpack分析代码，给没用到的导出打上/ unused harmony export /标记，相当于“告诉terser：这些是垃圾，删掉”。但它只负责“标记”，不负责“删除”，所以必须配合代码压缩工具（比如terser）才能生效。怎么开？在webpack.config.js的optimization里加：
module.exports = {
optimization: {
usedExports: true, // 开启标记功能
minimizer: [new TerserPlugin()] // 确保有压缩工具
}
}
不过注意：webpack在mode: 'production'时会默认开启usedExports和TerserPlugin，但如果你手动配了minimizer，记得把TerserPlugin加上，不然标记了也删不掉。
再说说sideEffects。这个参数是告诉webpack：“哪些文件可能有副作用，别乱删”。默认情况下，webpack会认为所有文件都有副作用，所以就算代码没被用到，也不敢删。解决方法是在package.json里声明哪些文件“没副作用”，可以放心删：
{
"sideEffects": [
".css", // CSS文件有副作用（会插入样式），保留
"/theme-chalk//.js" // 主题文件有副作用，保留
]
}
如果大部分文件都没副作用，可以直接写"sideEffects": false，表示“除了我列出来的，其他都没副作用”。之前优化一个组件库时，加了这句后，没用到的组件代码直接被删掉，包体积又减了150KB。
这里有个“反常识”的点：CSS文件其实是有副作用的（导入后会生成样式规则），如果不加到sideEffects里，Tree Shaking可能会把CSS删掉，导致样式丢失。所以一定要把CSS文件列进去，比如"*.css"或具体路径。
配置3：处理“隐性副作用”，别让代码“假装没被用”
有时候Tree Shaking失效，不是配置问题，而是代码里藏了“隐性副作用”——看起来没被用到的代码，其实在悄悄执行，这种代码Tree Shaking不敢删。
最常见的隐性副作用是“全局变量修改”。比如在工具函数文件里写了window.xxx = 'xxx'，或者修改了Array.prototype，这些都会被webpack认为有副作用。之前排查时发现一个文件里有Array.prototype.myFilter = function() {}，结果整个文件都没被Tree Shaking删掉，因为修改原型会影响全局。解决方法是把这类代码放到单独的文件，然后在package.json的sideEffects里列出来，告诉webpack“这个文件有副作用，保留”。
另一个坑是“立即执行函数（IIFE）”。比如(function() { console.log('初始化') })()，这种代码会在导入时执行，属于副作用。如果这个函数没被其他代码调用，又没声明副作用，Tree Shaking可能会删掉它，导致初始化逻辑丢失。这时候要么把它移到需要初始化的地方，要么声明为副作用文件。
还有一种情况是“条件导入”。比如if (process.env.NODE_ENV === 'development') { import('./dev-logger') }，这种动态导入在ESM里虽然支持，但Tree Shaking很难判断，可能会把dev-logger也打包进去。 用import()动态导入代替，或者用webpack的DefinePlugin定义环境变量，让条件判断在编译时确定结果。
配置4：第三方库“顽固分子”？用这2招搞定
就算业务代码配好了，第三方库也可能“拖后腿”。有些库本身不支持Tree Shaking，或者设计得很“臃肿”，导致冗余代码无法删除。这里有两个实用技巧，专治各种“顽固分子”。
第一招：用“模块化导出”的库代替“整体导出”的库。比如lodash虽然功能全，但默认导出整个库；而lodash-es是按模块导出的，可以只导入需要的函数，比如import { debounce } from 'lodash-es'，Tree Shaking会自动删掉其他没用到的函数。之前帮团队把import _ from 'lodash'改成import { debounce, throttle } from 'lodash-es'，直接少了300KB冗余代码。
第二招：用工具“拆包”。如果必须用不支持Tree Shaking的库（比如某些老的UI组件库），可以用babel-plugin-import这类工具手动拆包。比如antd默认会导入整个库的样式，但用babel-plugin-import可以只导入用到的组件和样式：
// babel.config.json里配置
{
"plugins": [
["import", {
"libraryName": "antd",
"libraryDirectory": "es",
"style": "css"
}]
]
}
这样导入import { Button } from 'antd'时，会被转换成import Button from 'antd/es/button'，只打包Button组件的代码，而不是整个antd库。
配置5：用可视化工具验证效果，别“瞎优化”
最后一点：优化完一定要验证效果，不然可能白忙活。最直观的工具是webpack-bundle-analyzer，它能生成包体积的可视化图表，让你清楚看到哪些代码被删掉了，哪些还在。
怎么用？先安装依赖：npm install webpack-bundle-analyzer save-dev，然后在webpack配置里加：
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
module.exports = {
plugins: [new BundleAnalyzerPlugin()] // 启动时会自动打开浏览器显示图表
}
运行打包命令后，浏览器会显示一个交互式图表，红色块是大文件，灰色块是冗余代码。优化前看看哪些是“大块头”，优化后再对比，体积减少多少一目了然。之前那个React项目，优化前图表里全是红色的lodash和没用到的组件，优化后这些块明显变小，总大小从2.3MB降到了1.3MB，正好减少40%，首屏加载时间从3.2秒提到1.4秒，用户反馈瞬间变好了。
除了看体积，还可以用source-map-explorer分析源码占比，或者在浏览器的“网络”面板看实际加载时间——这些都是验证Tree Shaking效果的好方法，别光看配置就觉得“肯定生效了”。
按照这5个配置一步步操作，Tree Shaking就能真正“摇”起来，包体积减少40%真的不难。记得优化后用webpack-bundle-analyzer对比一下，看看哪些代码被成功删掉了。如果你试了之后效果明显，或者遇到了其他坑，欢迎在评论区告诉我，咱们一起把前端性能优化做得更到位～
你平时开发的时候肯定遇到过这种情况：改一行代码，希望浏览器里马上就能看到效果，热更新快不快直接影响干活效率。这时候要是Tree Shaking跑来“捣乱”，把你暂时没用到的代码给删了，那麻烦可就大了——比如你写了个测试函数还没调用，结果Tree Shaking以为是冗余代码给删了，调试的时候想打断点，发现函数根本不在打包后的代码里，这不光影响进度，还容易让人误以为是自己代码写错了。所以工具早就想到这一点了，Tree Shaking本质是为了优化生产环境的包体积，开发环境反而要尽量保留完整代码，保证你调试的时候能看到所有逻辑，热更新也能跑得顺畅。
就拿Webpack来说吧，你在配置文件里虽然写了usedExports: true这些Tree Shaking相关的参数，但只要mode设的是development（开发模式），它就不会真的删掉代码。我之前帮朋友调一个Vue项目，特意看了下开发环境打包后的js文件，发现那些没用到的函数前面都加了注释，比如/ unused harmony export testFunc /，但函数本体还在那儿好好的。这就是Webpack的“聪明之处”：开发环境只做标记不删除，既让你知道哪些代码可能需要清理，又不影响调试——你在Chrome DevTools里看Sources面板，所有变量、函数名清清楚楚，打断点、看调用栈都跟写代码时一模一样，完全不用担心因为Tree Shaking导致调试信息丢失。等到切换到production模式打包时，它才会让Terser插件把这些带标记的代码彻底删掉，这样生产环境的包体积小了，开发环境的体验也没受影响，算是个挺贴心的设计。
Tree Shaking和代码压缩有什么区别？
Tree Shaking的核心是“删除未使用的代码（dead code）”，比如没被调用的函数、没引用的变量等，属于“减法优化”；而代码压缩（如Terser、UglifyJS）是对“已使用代码”进行精简，比如删除空格、缩短变量名、合并重复逻辑等，属于“精简优化”。两者通常配合使用：Tree Shaking先“减重”，压缩工具再“塑形”，共同减少包体积。
所有前端打包工具都支持Tree Shaking吗？
主流打包工具如Webpack（4+）、Rollup、Vite（基于Rollup）、esbuild（需配置）均支持Tree Shaking，但实现机制和配置细节不同。例如Rollup对Tree Shaking的支持更原生（因ESM静态分析能力强），Webpack需要显式配置usedExports和sideEffects，而Vite默认在生产环境启用Tree Shaking。需根据具体工具调整配置，不能一概而论。
Tree Shaking会影响开发环境的热更新或调试吗？
通常不会。Tree Shaking主要在生产环境（mode: 'production'）启用，开发环境为了保证热更新速度和调试体验，一般不会执行代码删除逻辑。例如Webpack在开发环境下，即使配置了Tree Shaking相关参数，也只会标记未使用代码而不删除，确保开发者能正常调试完整代码，不影响开发效率。
为什么用了Tree Shaking后，第三方库的体积还是很大？
可能是第三方库本身不支持Tree Shaking：① 库使用CommonJS模块（非ESM），无法静态分析依赖；② 库存在大量“隐性副作用”（如修改全局变量、自动执行初始化逻辑），导致Tree Shaking不敢删除；③ 库导出方式为“整体导出”（如import _ from 'lodash'），而非“按需导出”。解决办法：优先选ESM格式的库（如用lodash-es代替lodash），或通过babel-plugin-import等工具手动拆包。
如何快速判断Tree Shaking是否生效？
除了用webpack-bundle-analyzer等可视化工具对比包体积，还可通过“代码搜索法”验证：在生产环境打包后的.js文件中，搜索“确定未使用的代码片段”（如一个没被调用的测试函数名），若搜索结果为空，说明Tree Shaking已生效；若仍能找到，则可能存在配置问题（如模块类型错误、副作用未声明等）。
