Tree-shaking 在 TypeScript 项目中失效的根本原因是编译目标破坏静态可分析性：target: "es5" 导致类转函数、箭头函数降级、模块被 IIFE 包裹，使打包工具无法识别导出与引用关系。
Tree-shaking 在 TypeScript 项目中失效，常不是因为配置没开，而是编译目标破坏了静态可分析性——尤其是 target: "es5" 导致的闭包包裹、类转为函数声明、IIFE 封装等，让打包工具无法识别导出关系和引用路径。这不是“摇不掉”，而是“根本看不见谁被用了”。
TS 编译输出破坏 ESM 静态结构的三大典型表现
ES5 输出会主动改写原始模块结构，使 Tree-shaking 失效：
-
类被转成带闭包的立即执行函数（IIFE）：TypeScript 把
class Foo {}编译为var Foo = (function () { ... })();，整个结构脱离 ES 模块顶层作用域，打包器无法追踪export class Foo是否被引用 -
箭头函数、const/let 被降级为 var + 函数表达式：破坏了 export 的静态绑定语义，导致
export const fn = () => {}变成var fn = function() {}，Terser 等压缩器难以判定其是否“未使用” -
模块被包裹进闭包或全局命名空间：tsconfig 中
module: "commonjs"或"umd"时，即使写了export，最终输出仍是exports.xxx =形式，完全失去静态导入/导出的可分析性
真正有效的规避方式：守住 ESM 链路完整性
关键不是“怎么摇”，而是“别让它变脏”。必须确保从 TS 源码 → 编译输出 → 打包输入，全程保持纯 ESM 结构：
-
tsconfig.json 必须设
"module": "esnext"（不是 es2015/es2016）：这是唯一保证 TS 直接输出原生export/import语法的选项；es2015在某些版本仍可能退化为 IIFE -
target 至少为
"es2017"或更高（推荐"es2020"）：避免 class、async/await、箭头函数等被降级成闭包形态；现代打包工具（Webpack 5+/Vite/Rollup）均支持运行时兼容（靠 polyfill 或 browserslist 控制） -
禁用
downlevelIteration和importHelpers：这两项会注入辅助函数并改变模块结构，尤其importHelpers: true会让所有export依赖外部__extends等函数，间接引入副作用 - 不要让 tsc 直接参与构建流程：tsc 是类型检查+语法转换工具，不是打包器。正确做法是用 Vite / Webpack + ts-loader / swc / esbuild 做一体化转换，它们能跳过中间 .js 文件，直接解析 TS 源码做静态分析
验证是否真的“链路干净”
别只看配置，要盯住中间产物：
- 打开
node_modules/.bin/tsc --noEmit false --declaration false --emitDeclarationOnly false --outdir ./dist-esm输出的 .js 文件，确认里面是原生export const xxx =，没有var __createBinding、function __exportStar、(function () { ... })() - 在 Webpack 构建后查看 stats.json（加
--stats=verbose），搜索unused harmony export—— 如果大量存在，说明 Tree-shaking 已生效；如果全无，大概率是编译层已失守 - Vite 用户可启用
build.rollupOptions.treeshake: { moduleSideEffects: false, propertyReadSideEffects: false }强化判断，但前提是源码本身是 clean ESM
归根结底，TS 不是“配合 Tree-shaking”，而是“不能破坏它”。只要输出仍是标准 ESM，打包工具就能看清谁被 import，谁该扔。降级到 ES5 的代价，远不止体积变大——是把代码从“可静态分析”变成“不可知”。
