Webpack DLL Plugin构建的外部库无法找到宿主依赖，该如何解决？

这个问题我之前帮不少开发者排查过，核心是要确保类库和宿主项目的Webpack配置在外部依赖的声明和全局变量暴露上完全对齐，下面一步步来解决：

• 第一步：给类库正确配置外部依赖（externals）
  你的类库需要明确告诉Webpack：React和ReactDOM不需要打包进类库，而是要从宿主环境获取。在类库的webpack.config.js里添加如下配置：

  module.exports = {
    // ...其他基础配置
    externals: {
      // 键是你类库中import的包名，值是宿主环境中暴露的全局变量名
      react: 'React',
      'react-dom': 'ReactDOM'
    },
    output: {
      filename: 'mylibrary.js',
      // 配置为UMD格式，适配浏览器全局变量、CommonJS、ES模块等多种环境
      library: 'MyLibrary',
      libraryTarget: 'umd',
      globalObject: 'this' // 避免在Node和浏览器环境下的全局对象冲突
    }
  };
  

  这样Webpack打包时会跳过React，转而在运行时从全局window.React和window.ReactDOM中获取依赖。

• 第二步：检查宿主项目的DLL配置是否正确暴露全局变量
  宿主项目的DLL打包需要确保React被挂载到全局window对象上，同时DLL的manifest能被主Webpack配置识别：

  1. 编写DLL配置文件（比如webpack.dll.config.js）：

     const path = require('path');
     const webpack = require('webpack');
     
     module.exports = {
       entry: {
         vendors: ['react', 'react-dom', 'lodash']
       },
       output: {
         filename: '[name].js',
         path: path.resolve(__dirname, 'dist/dll'),
         // 这里的library名称要和DllPlugin的name完全一致
         library: '[name]_dll'
       },
       plugins: [
         new webpack.DllPlugin({
           name: '[name]_dll',
           path: path.resolve(__dirname, 'dist/dll/[name].manifest.json')
         })
       ]
     };
     

  2. 在宿主主Webpack配置中关联DLL manifest：

     const webpack = require('webpack');
     const path = require('path');
     
     module.exports = {
       // ...其他配置
       plugins: [
         new webpack.DllReferencePlugin({
           manifest: require('./dist/dll/vendors.manifest.json')
         })
       ]
     };
     

  3. 关键：确保HTML加载顺序正确
     必须先加载DLL的vendors.js，再加载你的类库，这样React全局变量才能提前存在：

     <script src="dist/dll/vendors.js"></script>
     <script src="path/to/mylibrary.js" crossorigin="anonymous"></script>
     

• 第三步：用peerDependencies规范类库的依赖要求
  在类库的package.json中把React设为peerDependencies，明确告诉宿主项目需要提供兼容版本的React，同时避免类库打包时混入React：

  {
    "peerDependencies": {
      "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
      "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
    },
    "devDependencies": {
      "react": "^18.2.0",
      "react-dom": "^18.2.0"
    }
  }
  

  这样开发类库时可以用devDependencies里的React做测试，实际发布后完全依赖宿主环境的React。

• 第四步：调试排查
  如果还是不行，打开浏览器控制台执行console.log(window.React)：

  • 如果输出undefined，说明vendors.js没正确暴露React全局变量，检查DLL配置的output.library和libraryTarget（可以尝试把libraryTarget设为'var'）；
  • 如果React存在但类库还是报错，检查类库的externals配置是否和全局变量名完全一致（比如是否写成了react: 'react'而不是'React'）。

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