Tree-shaking剔除未引用代码技巧全解

Tree-shaking 并非一键开启的“魔法开关”，其生效与否深度依赖模块规范（必须严格使用 ESM）、打包器能力（如 Webpack/Vite 对静态导入导出的分析）、第三方库支持（需明确 sideEffects 声明与子路径导出）以及代码写法细节（避免 export *、默认对象导出、隐式引用等“假死”导出）；许多看似失效的情况实为开发模式干扰、source map 膨胀或误判副作用所致，唯有在 production 构建后借助 stats 分析、可视化工具和逐层排查导出引用链，才能真正揪出阻碍代码瘦身的隐藏元凶。

Tree-shaking 为什么没生效？先看打包器和模块格式

Tree-shaking 不是开关，而是依赖打包器（如 webpack、vite、esbuild）对 ESM（import/export）静态结构的分析能力。用 require 或 CommonJS 模块（比如 lodash 的 const _ = require('lodash')）基本无法摇掉任何东西——因为执行时才决定引用关系。

实操建议：

• 确保你的代码和所用库都以 ESM 形式提供：查 package.json 中是否有 "type": "module" 或 "exports" 字段指向 .mjs / ESM 入口
• 避免混用：import { debounce } from 'lodash' 是 OK 的，但 import _ from 'lodash' + _.debounce 会把整个包引入
• vite 默认只对 node_modules 中明确标记 sideEffects: false 的包做深度摇；webpack 需在 optimization.usedExports: true 下配合 mode: 'production'

第三方库不支持 Tree-shaking？手动指定入口或别名

很多库（如 lodash、date-fns）虽支持 ESM，但默认 import 仍可能拉入未用代码，原因常是导出方式不够“纯”（比如有动态 key、export *、副作用初始化）。

实操建议：

• 优先用子路径导入：import debounce from 'lodash/debounce'，绕过主入口的聚合导出
• 对 date-fns 这类已按功能拆包的库，直接 import format from 'date-fns/format'，比 import { format } from 'date-fns' 更安全
• 在 webpack 中配 resolve.alias 把 lodash 映射到 lodash-es；vite 可用 optimizeDeps.include + depPrebundle 控制预构建行为

开发时看着没删，其实是 HMR 或 source map 干扰了判断

常见错觉：“我明明没用 fooUtils，但打包后体积没变”。往往不是 Tree-shaking 失败，而是你在 dev 模式下看产物（比如 webpack-dev-server 内存编译）、或启用了 devtool: 'source-map' 导致生成冗余映射信息。

实操建议：

• 只在 build 后检查真实产物：npx webpack --mode=production --stats=verbose，关注 chunks 和 provided exports 字段
• 用 rollup-plugin-visualizer 或 source-map-explorer 分析最终 .js 文件内容，确认某函数是否真被剔除
• console.log、debugger、未删除的注释、/*#__PURE__*/ 标记缺失，都可能让打包器误判为“有副作用”，不敢删

你的代码里藏着“假死”导出，Tree-shaking 看不见

即使你写了 export const unused = () => {}，只要它被任何地方 import 过（哪怕只是类型导入、测试文件、甚至被 IDE 自动补全加进去了），就不会被摇掉。更隐蔽的是：导出对象属性、默认导出解构、export * from —— 这些都可能让整块模块“活”下来。

实操建议：

• 检查所有 export * 语句，尤其跨包聚合时；改用显式命名导出：export { foo } from './foo'
• 避免默认导出对象：export default { a, b } → 摇不掉 a 就得留着整个对象；改用命名导出
• TypeScript 用户注意：import type 安全，但 import { X } from 'x' 即使只用于类型，也会触发实际导入（除非加 isolatedModules: true 并用 import type）

真正卡住 Tree-shaking 的，往往不是配置没开，而是某处 export 被意外引用，或某个库的 sideEffects 声明不准确。盯着 stats 输出里的 usedExports 和 providedExports 对照看，比调参数更快定位问题。

理论要掌握，实操不能落！以上关于《Tree-shaking剔除未引用代码技巧全解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！