如何用webpack构建支持按需引入、剔除冗余代码和依赖的JS组件库

1. 实现按需引入及Tree Shaking支持 #

要支持用户用命名导入的方式引入，且只打包用到的代码，核心是输出标准ESM模块并正确配置打包规则，步骤如下：

• 调整webpack输出配置：
  开启ES模块输出能力，webpack配置新增如下字段：

  module.exports = {
    experiments: {
      outputModule: true
    },
    output: {
      path: path.resolve(__dirname, 'dist'),
      filename: 'index.esm.js',
      library: {
        type: 'module'
      },
      clean: true
    }
  }
  

• 调整babel配置：
  禁止@babel/preset-env把ES模块转成CommonJS格式，避免Tree Shaking失效：

  {
    "presets": [
      ["@babel/preset-env", { "modules": false }],
      "@babel/preset-react"
    ]
  }
  

• 配置package.json声明模块信息：
  新增module字段指定ESM入口，新增sideEffects字段告知打包工具你的库无全局副作用（如果有样式文件等有副作用的内容，就把文件路径放进数组里）：

  {
    "main": "dist/index.cjs.js", // 可选，兼容CommonJS用户
    "module": "dist/index.esm.js",
    "sideEffects": ["*.css", "*.scss"]
  }
  

• 所有组件和工具方法统一用export语法从入口文件导出，不要使用module.exports。完成以上配置后，用户项目构建时会自动删除未引用的库代码。

2. 可选依赖配置方案 #

要避免强制用户安装所有未用到的依赖，可按如下规则处理：

• 调整package.json的依赖声明：
  把非通用的依赖从dependencies移到peerDependencies，再通过peerDependenciesMeta标记为可选，举个例子，假设你的图表组件依赖echarts，不是所有用户都用：

  {
    "peerDependencies": {
      "react": "^17.0.0 || ^18.0.0", // 公共必选依赖
      "echarts": "^5.0.0" // 可选依赖
    },
    "peerDependenciesMeta": {
      "echarts": {
        "optional": true
      }
    }
  }
  

  配置后如果用户没用到图表组件，不需要安装echarts，包管理工具也不会抛出强制安装错误。
• 代码层面做容错处理：
  在用到可选依赖的模块中做动态引入和异常捕获，避免用户未安装依赖时报错导致整个项目无法运行：

  import { useState, useEffect } from 'react'
  const Chart = (props) => {
    const [EchartsComp, setEchartsComp] = useState(null)
    useEffect(() => {
      import('echarts-for-react')
        .then(mod => setEchartsComp(mod.default))
        .catch(() => console.warn('使用图表组件需先安装echarts和echarts-for-react依赖'))
    }, [])
    if (!EchartsComp) return null // 也可以返回提示占位符
    return <EchartsComp {...props} />
  }
  export default Chart
  

• webpack配置里把可选依赖标记为externals，避免你打包的时候把这些依赖打进你的库文件里：

  module.exports = {
    externals: {
      'echarts': 'echarts',
      'echarts-for-react': 'echarts-for-react'
    }
  }
  

• 可选优化：可以配置多入口打包，给每个组件/工具生成单独的出口文件，支持用户import Chart from 'my-lib/Chart'的方式单独引入，进一步减少引入体积。

补充最佳实践 #

• 发布前可以用npm pack生成本地安装包，在测试项目中安装验证Tree Shaking是否生效、可选依赖是否会被强制安装
• 如果不需要webpack的特殊能力，也可以选择rollup或者tsup作为库构建工具，这类工具对库打包的场景适配度更高，配置更简洁

内容的提问来源于stack exchange，提问作者Sebas Fernandez