2023年如何正确构建ES模块包的导出结构？

API 探路者

2026-7-25

ESM 包导出策略：选择、适配与实践

不止两种选择，还有中间方案

你提到的两种是主流方向，但并非仅有的选项，还有更灵活的中间路线：

分层局部重导出：不把所有内容堆到根目录index.mjs，而是按功能模块在子目录设置index.mjs，比如src/utils/index.mjs只导出该目录下的工具函数，根目录index.mjs再选择性导出核心模块。这样既保留了裸导入的便捷，又避免了根导出过于臃肿。
显式入口映射（推荐）：利用package.json的exports字段定义导出点，完全替代目录index文件的作用，示例配置：
```
{
  "name": "@my-scope/my-lib",
  "type": "module",
  "exports": {
    ".": "./src/index.mjs",
    "./utils": "./src/utils/index.mjs",
    "./utils/foo": "./src/utils/foo.mjs"
  }
}
```
这种方式完全由配置控制对外暴露的路径，不需要依赖目录index，也能实现裸导入和精准路径导入的双重支持。

两种基础方式都合规，核心看你的包定位和维护成本：

全局重导出（带目录index）
- 优势：使用者可以用简洁的裸导入import { Foo } from '@my-scope/my-lib'，上手门槛低；同时支持路径导入满足进阶需求。
- 劣势：你遇到的「忘记重导出」问题是通病，容易导致使用者体验不一致；如果包体积较大，全局导出会降低Tree Shaking的效率（现代打包工具能兼容，但不如精准导出高效）。
单入口导出
- 优势：结构极简，维护成本极低，完全避免漏导出的问题；Tree Shaking效果最优。
- 劣势：使用者如果只需要某个子模块，要么导入整个包，要么自行引用内部文件（破坏封装性），对大型工具包不友好。

目前没有颠覆性的新标准，但package.json的exports字段是ESM时代的官方推荐方案，比传统index文件更灵活：

可以限制导出路径，避免使用者依赖未公开的内部文件；
支持区分Node.js和浏览器环境的导出逻辑；
配合import maps使用时，不会增加复杂度——import maps仅负责将裸包名映射到实际URL，不管你用哪种导出策略，只要映射正确就能正常工作。反而exports定义的导出点，在import maps中可以更精准地映射，减少歧义。

既然你偏好裸导入的便捷性，又不想因为漏导出掉链子，可以试试：

自动生成重导出：写个简单的Node.js脚本，遍历src目录下的模块，自动收集导出内容并更新根目录index.mjs；或者用tsc（即使不用TypeScript，也可以配置declaration: false来生成重导出代码）。
切换到exports配置：把需要对外暴露的模块全部显式写在package.json的exports里，不需要依赖目录index，既能实现裸导入和路径导入，又能彻底避免漏导出的问题。

不管选哪种策略，对import maps的复杂度影响都很小：

如果用全局重导出，import maps只需要映射@my-scope/my-lib到你的根index.mjs即可，使用者的路径导入会自动基于这个映射解析。
如果用exports配置，import maps的映射逻辑和全局重导出一致，因为exports定义的路径会被ESM解析器自动识别，import maps仅需处理根包名的映射。

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