Tree Shaking 失效主因是导入方式阻碍静态分析，如 import _ from 'lodash' 或误用 CommonJS 入口；应改用 ESM 按需引入、验证库的 exports/module 字段，并通过 Bundle Analyzer 确认实际打包内容。
Tree Shaking 失效常因“看似按需引入，实则触发全量加载”——尤其在使用 导出大量工具函数的工具库（如 lodash、date-fns、ramda）时。关键不是“有没有 import”，而是“导入方式是否让打包器能静态分析出未使用代码”。下面从排查路径和典型陷阱两方面说明。
确认是否真的触发了全量引入
先看打包产物，而非源码逻辑：
- 用 Webpack Bundle Analyzer 或 Rollup Plugin Visualizer 可视化最终 bundle，搜索疑似库名（如
lodash），看是否整个模块被打包进来，而不仅是用到的函数 - 检查 source map 中对应模块的原始路径：如果看到
node_modules/lodash/lodash.js或node_modules/ramda/dist/ramda.js，基本是全量引入；若为node_modules/lodash/isEmpty.js或node_modules/date-fns/esm/format/index.js，才是正确按需 - 在构建后生成的
stats.json中搜索该库的reasons字段，可定位是哪行import拉入了整个包
常见导致全量引入的导入写法
以下写法看似简洁，实则破坏 Tree Shaking：
-
import _ from 'lodash'—— 引入默认导出（即全量lodash.js），即使只用_.isEmpty，ESM 静态分析也无法剥离其他方法 -
import * as utils from 'my-utils'—— 若my-utils的入口文件是index.js且内部export * from './all-functions'，等同于全量透出 -
import { debounce } from 'lodash-es'✅ 正确，但若误写成import { debounce } from 'lodash'❌ 就会走 CommonJS 入口，失去 ESM 静态可析性 -
import dayjs from 'dayjs'—— 全量；应改用import dayjs from 'dayjs/esm'或更推荐的按需插件式引入：import dayjs from 'dayjs/esm'; import relativeTime from 'dayjs/esm/plugin/relativeTime'; dayjs.extend(relativeTime)
验证库本身是否支持 Tree Shaking
不是所有标榜“ESM”的库都真正可摇：
立即学习“Java免费学习笔记（深入）”；
- 查
package.json中是否有"type": "module"或"exports"字段明确指向 ESM 入口（如"./dist/index.esm.js"） - 打开
node_modules/xxx/package.json，看"main"是否指向 CommonJS 文件（如index.js），而"module"或"exports"是否指向真正的 ESM 版本 - 部分库（如早期版本
lodash-es）存在__esModule标记缺失或动态require，也会干扰分析；建议锁定已知稳定的版本（如lodash-es@4.17.21+）
修复与替代方案
优先选择明确支持 ESM + 按需的实践：
- 换用原生支持 ESM 拆分的库：用
date-fns（天然每个函数独立文件）代替moment；用clsx代替classnames（后者无 ESM 入口） - 强制指定 ESM 入口：在 Webpack 中配置
resolve.alias，例如{ 'lodash': 'lodash-es' }；Rollup 可用resolve({ browser: true })启用pkg.browser字段 - 借助 Babel 插件自动转换：如
@babel/plugin-transform-modules-commonjs配合lodash-babel-plugin，将import { debounce } from 'lodash'自动重写为import debounce from 'lodash/debounce' - 对自研库，确保
index.js不做聚合导出，改为在package.json中用"exports"精确声明各子路径入口，例如："exports": {<br> ".": "./dist/index.js",<br> "./debounce": "./dist/debounce.js",<br> "./throttle": "./dist/throttle.js"<br> }
