打造支持TreeShaking的通用工具库指南

想要打造一个高效、轻量的通用工具库？**如何打造支持Tree Shaking的通用工具库**？关键在于让未使用的代码在打包时被静态分析工具识别并移除，从而减小最终bundle体积，提升应用性能。本文将详细介绍如何通过遵循ES模块语法、避免副作用、合理配置打包格式等关键步骤，构建一个真正支持Tree Shaking的工具库。核心要点包括：采用静态`import/export`语法，每个函数单独文件导出，并在入口文件重新导出；在`package.json`中正确配置`"sideEffects"`属性，声明无副作用或列出真实副作用文件；以及使用Rollup等工具输出ESM和CJS等多种格式，以兼容不同环境。最后，通过实际测试验证Tree Shaking效果，确保未引用函数被成功移除。遵循这些最佳实践，你的工具库就能被消费端有效Tree Shaking，显著优化项目性能。

要构建支持 Tree Shaking 的工具库，需使用 ESM 语法、避免副作用、合理配置打包格式。核心是采用静态 import/export，每个函数单独文件导出，入口文件重新导出；在 package.json 中设置 "sideEffects": false（若有真实副作用则列出）；通过 Rollup 输出 esm 和 cjs 格式；最后验证未引用函数是否被移除。

要构建一个支持 Tree Shaking 的通用工具库，核心是确保未使用的代码在打包时能被静态分析工具（如 Webpack、Rollup 或 Vite）识别并移除。这要求你在项目结构、模块导出方式和打包配置上遵循特定规范。

使用 ES 模块语法

Tree Shaking 依赖于静态的 import / export 语法，因此必须使用 ES6 模块（ESM），而不是 CommonJS（require / module.exports）。

• 每个工具函数单独定义在一个文件中
• 使用 export 导出具体函数，避免默认导出或命名空间导出
• 入口文件使用命名导出重新导出所有功能

示例：

// src/utils/format.js
export function formatDate(date) { /* ... */ }
export function formatNumber(num) { / ... / }
// src/index.js
export  from './utils/format';
export  from './utils/validate';

避免副作用

“副作用”指模块执行时除了导出值之外还产生其他行为（如修改全局变量、执行 console.log 等）。打包工具若检测到副作用，默认不会删除该模块，即使其中部分函数未被引用。

在 package.json 中声明 "sideEffects": false，告诉打包工具整个库无副作用，可安全进行 Tree Shaking。

{
  "name": "my-utils",
  "main": "dist/my-utils.cjs",
  "module": "dist/my-utils.esm.js",
  "sideEffects": false
}

• 如果你的库包含 CSS 引入或 polyfill 等真实副作用，应将它们列在 sideEffects 数组中
• 例如："sideEffects": ["./src/polyfill.js", "*.css"]

合理设计打包输出格式

为了兼容不同环境，建议同时输出多种模块格式：

• ESM（.esm.js）：保留 import/export，供支持 Tree Shaking 的现代打包工具使用
• CommonJS（.cjs）：供 Node.js 或旧版构建工具使用
• 可选：UMD 格式用于浏览器直接引入

推荐使用 Rollup 或 Vite 打包，天然对 Tree Shaking 友好。

Rollup 配置示例（rollup.config.js）：

export default [
  {
    input: 'src/index.js',
    output: {
      file: 'dist/my-utils.esm.js',
      format: 'esm'
    }
  },
  {
    input: 'src/index.js',
    output: {
      file: 'dist/my-utils.cjs',
      format: 'cjs'
    }
  }
]

发布前验证 Tree Shaking 效果

构建完成后，应手动测试 Tree Shaking 是否生效。

• 创建一个测试项目，只引入库中的某个函数：import { formatDate } from 'my-utils'
• 使用 Webpack 或 Vite 构建该项目，并查看生成的 bundle
• 确认未引用的函数（如 formatNumber）没有出现在最终代码中

也可使用工具如 webpack-bundle-analyzer 分析打包体积，辅助判断。

基本上就这些。只要保证 ESM 导出、无副作用声明、合理打包配置，你的工具库就能被消费端有效 Tree Shaking。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《打造支持TreeShaking的通用工具库指南》文章吧，也可关注golang学习网公众号了解相关技术文章。