背景

消费者开始导入 src/internal 后,内部重构就变成跨团队接口变更。公开入口越小,模块内部越容易演进。

核心判断

  1. package exports 列出受支持入口,入口文件只导出必要类型与函数。
  2. 避免泄露第三方库的复杂内部类型。
  3. 弃用变更配合文档、版本策略与实际调用统计。

最小示例

下面保留核心逻辑;业务类型、调用入口和环境配置按项目补齐。

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

边界与误区

示例是 package.json 片段,发布目录结构与 module 类型要匹配。声明入口与运行时入口都需验证,CJS/ESM 双模式不能仅靠一个 types 字段假设兼容。

验证方式

用真实消费者项目安装打包产物,分别验证类型解析与运行;尝试导入内部路径,确认受支持的解析器会拒绝。

小结

通过 package exports 公开最小 API,隐藏实现类型并管理弃用周期。