Webpack构建UMD库用动态导入在其他项目引入时触发ChunkLoadError

核心问题 #

UMD规范是为兼容多环境（浏览器、Node.js、AMD）设计的，默认不支持异步代码分割——当你在库中用import()拆分代码时，生成的chunk文件在宿主项目里找不到正确加载路径，就会触发ChunkLoadError。而普通同步导入没有异步加载逻辑，所以不会报错。

解决方案 #

1. 配置Webpack输出字段，指定chunk加载路径 #

在库的Webpack配置里，明确异步chunk的公共路径，确保宿主项目能定位到这些文件：

module.exports = {
  output: {
    filename: '[name].umd.js',
    library: 'YourLibraryName',
    libraryTarget: 'umd',
    globalObject: 'this',
    // 关键：设置异步chunk的文件名和公共路径，根据部署场景调整
    chunkFilename: '[name].chunk.js',
    publicPath: '' // 若库和宿主静态资源同目录设为''，放CDN则填CDN地址
  }
};

2. 让宿主项目动态配置公共路径 #

如果库的chunk会放在不同位置，可以在库中暴露一个方法让宿主自定义路径：

// 库的入口文件
export let __webpack_public_path__ = '';

export function setPublicPath(path) {
  __webpack_public_path__ = path;
}

// 异步加载模块的代码
export async function loadFeature() {
  const module = await import('./features/SomeFeature');
  return module.default;
}

宿主项目使用时先设置路径再调用：

import { setPublicPath, loadFeature } from 'your-library';

// 按宿主项目的静态资源路径配置
setPublicPath('/path/to/library/chunks/');

// 之后调用异步加载方法
loadFeature().then(feature => {
  // 使用功能
});

3. 精准控制代码分割范围 #

如果库体量小，只需要分割特定模块，用splitChunks配置精准控制，避免多余chunk：

module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'async',
      cacheGroups: {
        feature: {
          test: /features\/SomeFeature/,
          name: 'feature-chunk',
          enforce: true
        }
      }
    }
  }
};

4. 测试时确保chunk文件被正确复制 #

在测试项目中，要把库生成的所有chunk文件（包括主文件和分割后的chunk）复制到宿主静态资源目录，或者通过npm link确保文件可访问。比如用copy-webpack-plugin打包测试项目时复制chunk：

const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: 'node_modules/your-library/dist/*.chunk.js', to: 'static/js/[name][ext]' }
      ]
    })
  ]
};

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