什么时候需要考虑 Tree Shaking 优化

Nuxt 3 项目在生产构建后，如果发现 js 或 css 文件体积明显偏大，加载时间变长，通常需要检查 tree-shaking 是否生效。tree-shaking 依赖 ES module 的静态分析，在构建时移除未引用的导出。但 Nuxt 3 使用了 Nitro 作为服务端引擎，加上 Vite 或 Webpack 的二次打包，很容易因为配置不当或第三方库的 sideEffects 声明不准确，导致冗余代码被保留。适合优化的场景包括：使用了大型 UI 库但只用了少数组件、引入了工具函数库但只调用了几个方法、或者构建产物中出现明显不属于业务逻辑的模块。在动手调整前，先确认你用的是 Vite 模式还是 Webpack 模式（Nuxt 3 默认 Vite），因为不同打包器的 tree-shaking 行为略有差异。

识别问题：生成打包分析报告

要判断哪些模块未被正确 tree-shake，最直接的方法是生成打包分析报告。在 Nuxt 3 中，可以通过配置 nitro 的 analyze 选项或使用 rollup-plugin-visualizer 插件来生成可视化图表。重点关注那些体积异常大但实际并未被业务代码引用的模块，比如未使用的工具函数、全部导入的组件库等。如果发现某个库的几乎所有导出都出现在最终产物中，说明 tree-shaking 可能失效，需要进一步检查该库的 sideEffects 声明。

具体操作：在 nuxt.config.ts 中增加 nitro: { analyze: true }，然后执行 nuxi build，构建完成后会在 .output 目录下生成 report.html。如果使用 rollup-plugin-visualizer，可以在 Vite 插件中配置。打开分析报告后，按大小排序，优先排查那些体积超过几十 KB 且引用次数为 0 的模块。注意，有些模块虽然被引用但实际只在特定分支执行，静态分析无法识别，需要结合代码逻辑判断。

优化侧配置：sideEffects 与依赖预处理

优化 tree-shaking 的核心是正确配置 package.json 中的 sideEffects 字段。如果项目使用了第三方库，确保该库声明了 sideEffects: false 或明确列出有副作用的文件（如 CSS 文件）。对于自己的模块，可以在 nuxt.config.ts 的 vite 或 webpack 配置中显式设置 sideEffects: false。此外，在构建配置中启用 optimizeDeps 并排除不必要的依赖，减少预构建体积。注意，修改后必须重新构建并验证分析报告，避免误删必需的副作用代码。

针对第三方库，可以检查其 package.json 中的 sideEffects 字段。很多流行库（如 lodash-es、dayjs）已经正确声明，但有些库可能没有声明或声明不完整。如果你确定自己的使用方式不依赖副作用，可以在项目根目录的 package.json 中添加 "sideEffects": false，但这样做风险较高，因为会影响所有模块。更稳妥的做法是在 nuxt.config 中针对特定路径设置：vite: { build: { rollupOptions: { treeshake: { moduleSideEffects: (id) => false } } } }，但需要配合白名单。另外，在 nuxt.config.ts 中通过 vite.optimizeDeps.include 可以提前打包某些依赖，通过 exclude 可以排除不必要的预构建，减少产物体积。

常见陷阱：副作用误删与动态导入

一个常见的陷阱是：使用了仅包含副作用的模块（如全局样式、polyfill）时，如果错误地将其标记为 sideEffects: false，会导致构建产物缺少这些关键功能。例如，某些 UI 库在组件内部引入 CSS，但 CSS 本身有副作用，若整个库被标记为无副作用，样式将被 tree-shake 掉。另一种情况是动态导入（如 import('module')）会阻断静态分析，使 tree-shaker 无法确定哪些子模块被使用，从而保留整个动态加载的 chunk。应尽可能用静态导入代替动态导入，或在动态导入中只引用必要的路径。

检查动态导入的具体方法：在打包分析报告中，如果看到某个 chunk 体积很大且包含多个模块，但对应的动态导入语句只引用了其中一个函数，就要重构为 import('./module/subModule') 的形式。对于 UI 库，如果按需引入后样式丢失，通常是因为库的 sideEffects 声明中已经把 CSS 排除在外，需要手动在 nuxt.config.ts 的 css 选项中引入全量样式，或者使用支持按需加载的变体（如 unplugin-vue-components）。

检查效果与风险边界

检查 tree-shaking 效果可以用浏览器开发者工具的 Coverage 面板（Chrome DevTools），加载页面后记录代码覆盖率。高亮为红色或灰色的部分即从未执行过的代码，可能属于未被 tree-shake 的冗余代码。更精确的做法是使用 webpack-bundle-analyzer 或 rollup-plugin-visualizer 生成的报告，查看每个模块的引用次数和大小。如果发现某个模块引用次数为 0 但仍被打包，说明需要排查其导入路径或 sideEffects 配置。注意，覆盖率数据受运行时交互影响，需结合静态分析综合判断。

在优化 tree-shaking 时，必须警惕对全局状态、副作用依赖（如 CSS 动画库、自定义指令）的误删。例如，一个在入口文件中通过 import './some-module' 导入的模块，如果它修改了原型链或全局对象，就不能标注为 sideEffects: false。建议先在开发环境开启 source map，用浏览器检查是否有缺失的功能或样式。同时，优先在打包分析报告中排除那些明显未使用的体积大户，逐步调整配置，每次只改动一项配置并观察构建产物变化，避免一次性改动过多导致定位问题困难。

实际操作步骤：先通过分析报告标记出一个体积大且看似无用的模块，比如一个完整的图标库。如果确认没有在任何业务代码中引用，可以尝试在 nuxt.config 中设置 vite: { build: { rollupOptions: { external: ['icon-library'] } } } 并构建验证。如果页面功能正常，说明可以安全移除。对于有副作用的模块，可以先用 import './style.css' 的方式保留，只在具体需要的地方导入。每次调整后重新生成分析报告，对比前后体积变化，同时用浏览器测试核心功能。如果构建产物变小但页面出现样式错乱或功能缺失，立即回退改动，检查 sideEffects 白名单是否遗漏。