package.json中main、module与exports字段的差异及配置优劣对比

核心差异 #

main + module 是早期社区为了兼容ESM和CJS推出的非标准化方案，exports 是Node.js 12+ 官方推出的标准化入口控制方案，二者的核心区别主要在三个方面：

• 支持范围不同：main 是所有Node.js版本都支持的默认CJS入口，module 仅被webpack、rollup、vite等前端打包工具识别，Node.js原生环境不认该字段；exports 是Node.js 12及以上版本原生支持的配置，目前主流打包工具也已全部兼容。
• 控制粒度不同：main + module 只能定义整个包的根入口，无法限制用户引入包内的子路径；exports 除了按引入方式分配入口外，还可以自定义子路径映射、禁止内部私有路径被外部引用，避免用户依赖未对外暴露的内部逻辑。
• 优先级不同：如果包同时配置了三类字段，支持exports的环境会优先读取exports配置，直接忽略main和module。

方案一：main + module 配置 #

优点 #

• 兼容性极强：支持所有Node.js版本的CJS引入，也兼容几乎所有新旧版本的前端打包工具，能满足打包工具对ESM tree shaking的需求。
• 配置简单无学习成本，是过去几年跨平台兼容类库的通用配置方案。

缺点 #

• Node.js原生环境不支持ESM引入：就算配置了module字段，在Node.js中直接用import引入包时，依然会走main对应的CJS文件，无法使用ESM的原生特性。
• 无入口限制能力：用户可以随意引入包内的任意文件，比如import 'mylib/src/internal/util.js'，很容易依赖到你没有对外承诺稳定的内部逻辑，后续迭代极容易出现兼容性问题。
• 扩展能力弱：只能区分CJS和ESM入口，无法针对不同运行环境（Node.js/浏览器/electron等）做差异化的入口分发。

方案二：exports 配置 #

优点 #

• Node.js原生级支持：Node.js 12+ 环境下可以原生识别import和require对应的不同入口，不需要依赖打包工具就能同时支持两种引入方式。
• 能力更全面：除了按引入方式区分入口，还可以配置子路径别名、多环境入口、限制私有路径访问，大幅降低后续维护的兼容性成本。
• 是Node.js官方当前推荐的标准配置方案，后续的生态兼容性会越来越好。

缺点 #

• 低版本环境兼容差：Node.js 12以下的版本完全不识别exports字段，如果你的包需要支持Node.js 10及以下的老旧环境，单独配置exports会导致低版本环境引入包失败。
• 老旧打包工具支持差：比如webpack 4以下的老旧构建工具不认exports字段，会出现找不到包入口的问题。
• 配置规则更复杂，有一定学习成本，路径映射规则写错很容易出现引入报错的问题。

通用推荐实践 #

如果你的包需要兼容老旧Node.js版本或者老旧构建工具，可以同时配置两种方案：低版本环境自动降级走main + module的逻辑，高版本环境走exports的逻辑，能覆盖绝大多数使用场景。

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