Webpack为何不直接使用库的CommonJS版本而选择转换ESM模块？

问题根因 #

你在 package.json 里的配置没有错误，webpack 优先读取 module 字段的 ESM 入口是默认设计：webpack 从 2.0 版本开始就将 module 字段的优先级设置为高于 main 字段，目的是优先加载 ESM 格式的代码以支持 Tree Shaking 优化，不管当前项目最终输出的是 CommonJS 还是 ESM 格式，都会优先走 ESM 入口再做转译。
你遇到的 Cannot access 'Agile' before initialization 错误，是 ESM 转 CommonJS 过程中变量提升/初始化顺序处理差异导致的：ESM 采用静态解析的导入导出逻辑，而 CommonJS 是运行时动态加载，webpack 的转译逻辑如果遇到你的 ESM 代码里存在循环引用、或者变量导出顺序早于初始化顺序的场景，就会触发这类初始化前访问的错误。

可行解决方案 #

1. 新增 exports 字段明确入口映射
   这是目前兼容性最好的方案，exports 字段是 Node.js 以及所有现代打包工具支持的标准入口配置，优先级高于 module 和 main 字段，你可以在 package.json 中添加以下配置，明确区分不同引入方式对应的入口：

{
  "exports": {
    ".": {
      "require": "./dist/index.js",
      "import": "./dist/esm/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}

配置后，使用 require 引入你的库时会自动走 CommonJS 入口，使用 import 引入时走 ESM 入口，不会出现 webpack 强行用 ESM 转 CommonJS 的情况，同时保留两种规范的支持。

2. 修复 ESM 产物的代码逻辑
   你可以排查 ESM 版本代码中 Agile 相关变量的声明、导出顺序，以及是否存在循环引用的场景：

• 确保所有导出的变量在导出前已经完成初始化
• 调整循环引用的依赖顺序，或者将循环引用的部分拆分到单独的文件
  调整后即使 webpack 转译 ESM 代码也不会触发初始化顺序错误。

3. 给使用方提供临时配置方案
   如果暂时无法修改库的代码，你可以告知使用你的库的开发者，在 webpack 配置中调整 resolve.mainFields 的优先级，让 CommonJS 场景下优先读取 main 字段：

// webpack.config.js 中针对 CommonJS 输出场景添加
module.exports = {
  resolve: {
    mainFields: ['main', 'module']
  }
}

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