UMD库打包完整配置指南：从入门到精通

什么是UMD模块规范

UMD（Universal Module Definition）是一种通用的JavaScript模块定义规范，它能够兼容多种模块加载环境。在当今前端开发中，我们经常需要让代码在不同的环境中运行，比如在浏览器中直接使用、通过AMD加载器（如RequireJS）加载，或者在Node.js环境中运行。UMD规范就是为了解决这种跨环境兼容性问题而诞生的。

UMD的核心思想是通过条件判断来检测当前环境支持的模块系统，然后采用相应的方式导出模块。这种灵活性使得开发者可以编写一次代码，就能在多种环境中运行，大大提高了代码的可复用性。

UMD的基本结构

一个典型的UMD模块通常包含以下结构：

(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    // AMD环境
    define(['dependency'], factory);
  } else if (typeof exports === 'object') {
    // CommonJS环境
    module.exports = factory(require('dependency'));
  } else {
    // 浏览器全局变量
    root.MyModule = factory(root.dependency);
  }
}(this, function (dependency) {
  // 模块主体代码
  var MyModule = function() {
    // 模块实现
  };

  return MyModule;
}));

这种结构通过立即执行函数（IIFE）来创建闭包，避免污染全局命名空间。函数接收两个参数：root（全局对象）和factory（工厂函数）。在函数内部，通过检测不同的模块系统特征，采用相应的模块定义方式。

UMD打包环境搭建

安装必要的工具

要开始UMD打包，首先需要安装一些必要的构建工具。以下是推荐的工具链：

# 初始化项目
npm init -y

# 安装Webpack（模块打包器）
npm install --save-dev webpack webpack-cli

# 安装Babel（JavaScript编译器）
npm install --save-dev @babel/core @babel/preset-env babel-loader

# 安装其他有用的工具
npm install --save-dev webpack-bundle-analyzer clean-webpack-plugin

配置文件详解

创建webpack.config.js配置文件：

const path = require('path');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  // 入口文件
  entry: './src/index.js',

  // 输出配置
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'my-library.[name].js',
    library: 'MyLibrary', // 库的全局变量名
    libraryTarget: 'umd', // 模块化规范
    globalObject: 'this', // 全局对象
    umdNamedDefine: true // 对UMD模块命名
  },

  // 模块解析规则
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  },

  // 插件配置
  plugins: [
    new CleanWebpackPlugin(),
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      openAnalyzer: false
    })
  ],

  // 外部依赖配置
  externals: {
    lodash: {
      commonjs: 'lodash',
      commonjs2: 'lodash',
      amd: 'lodash',
      root: '_'
    }
  },

  // 模式配置
  mode: 'production',

  // 开发工具
  devtool: 'source-map'
};

详细配置解析

输出配置详解

输出配置是UMD打包的核心部分，各个配置项的作用如下：

• filename: 输出文件的命名规则，可以使用[name]、[hash]等占位符
• library: 定义库的全局变量名称，在浏览器环境中会挂载到window对象上
• libraryTarget: 设置为'umd'表示使用UMD模块规范
• globalObject: 确保在不同环境中都能正确引用全局对象
• umdNamedDefine: 为AMD模块提供命名，便于调试

外部依赖管理

在UMD打包中，正确处理外部依赖至关重要。externals配置项告诉webpack哪些模块应该被视为外部依赖，不打包到最终的bundle中：

externals: {
  // 键名是import时的模块名，值是对应不同环境的变量名
  'react': {
    commonjs: 'react',
    commonjs2: 'react',
    amd: 'react',
    root: 'React'
  },
  'react-dom': {
    commonjs: 'react-dom',
    commonjs2: 'react-dom',
    amd: 'react-dom',
    root: 'ReactDOM'
  }
}

这种配置确保了在不同环境中都能正确引用这些外部库，同时避免将它们打包进最终的bundle，减小文件体积。

高级配置技巧

多入口配置

对于复杂的库，可能需要支持多个入口点：

module.exports = {
  entry: {
    main: './src/index.js',
    utils: './src/utils/index.js',
    plugins: './src/plugins/index.js'
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js',
    library: ['MyLibrary', '[name]'],
    libraryTarget: 'umd',
    globalObject: 'this'
  }
};

环境特定配置

根据不同环境调整配置：

module.exports = (env, argv) => {
  const isProduction = argv.mode === 'production';

  return {
    // 基础配置
    mode: argv.mode || 'development',

    // 生产环境优化
    optimization: {
      minimize: isProduction,
      splitChunks: isProduction ? {
        chunks: 'all',
        minSize: 30000,
        maxSize: 244000
      } : false
    },

    // 开发环境配置
    devtool: isProduction ? 'source-map' : 'eval-source-map',

    // 其他配置...
  };
};

实战案例：构建一个工具库

让我们通过一个完整的例子来演示如何构建一个UMD格式的工具库。

项目结构

my-utils-library/
├── src/
│   ├── index.js
│   ├── math.js
│   └── string.js
├── package.json
├── webpack.config.js
└── README.md

源代码实现

src/math.js:

/**
 * 数学工具函数
 */

export function add(a, b) {
  return a + b;
}

export function subtract(a, b) {
  return a - b;
}

export function multiply(a, b) {
  return a * b;
}

export function divide(a, b) {
  if (b === 0) {
    throw new Error('除数不能为零');
  }
  return a / b;
}

src/string.js:

/**
 * 字符串工具函数
 */

export function capitalize(str) {
  if (typeof str !== 'string') {
    throw new TypeError('参数必须是字符串');
  }
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function reverse(str) {
  if (typeof str !== 'string') {
    throw new TypeError('参数必须是字符串');
  }
  return str.split('').reverse().join('');
}

src/index.js:

/**
 * 主入口文件
 */

import * as math from './math';
import * as string from './string';

// 导出所有工具函数
export { math, string };

// 默认导出
export default {
  math,
  string
};

完整的webpack配置

const path = require('path');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  entry: './src/index.js',

  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'my-utils.min.js',
    library: 'MyUtils',
    libraryTarget: 'umd',
    globalObject: 'this',
    umdNamedDefine: true
  },

  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              [
                '@babel/preset-env',
                {
                  targets: {
                    browsers: ['last 2 versions', 'ie >= 11']
                  },
                  modules: false
                }
              ]
            ]
          }
        }
      }
    ]
  },

  plugins: [
    new CleanWebpackPlugin()
  ],

  externals: {
    // 如果有外部依赖，在这里配置
  },

  optimization: {
    minimize: true
  },

  mode: 'production'
};

package.json配置

确保package.json中包含正确的入口点和模块定义：

{
  "name": "my-utils-library",
  "version": "1.0.0",
  "description": "一个实用的JavaScript工具库",