package.json exports字段如何配置多入口TS类型声明

类型声明导出规则 #

从 TypeScript 4.7 版本开始，TS 原生支持在 exports 字段中通过 types 条件声明对应入口的类型文件，匹配逻辑和 Node.js 原生的条件导出规则完全一致：每个入口的 types 条件必须放在所有其他条件的最顶部。TypeScript 会按从上到下的顺序匹配条件，一旦命中非 types 的 JS 入口条件，就会停止向后查找，直接导致类型声明找不到。

是否需要保留顶层 types 字段 #

按你需要兼容的环境判断即可：

• 如果你声明的库最低支持 TypeScript 4.7 及以上版本，且所有导出入口都在 exports 中配置了正确的 types 条件，可以直接删除顶层 types 字段。
• 如果你需要兼容 TypeScript 4.6 及更早版本，或者部分老旧构建工具不识别 exports 内的类型配置，建议保留顶层 types 字段作为主入口类型的兜底，不会和 exports 配置产生冲突。
• 同理，旧的 main、module 字段也可以作为低版本工具链的兜底保留，高版本 Node、Webpack 等工具会优先读取 exports 配置，不会受这些旧字段影响。

多导出入口的正确配置示例 #

每个独立导出入口（包括主入口 "."）都需要单独配置对应的 types 条件，始终放在该入口条件块的第一位。以你给出的配置为例，假设编译后dist目录下每个JS模块对应同名的 .d.ts 类型文件，修正后的配置如下：

{
  "exports": {
    ".": {
      "types": "./dist/A.d.ts",
      "import": "./dist/A.mjs",
      "require": "./dist/A.js"
    },
    "./A": {
      "types": "./dist/A.d.ts",
      "import": "./dist/A.mjs",
      "require": "./dist/A.js"
    },
    "./B": {
      "types": "./dist/B.d.ts",
      "import": "./dist/B.mjs",
      "require": "./dist/B.js"
    }
  },
  // 以下为旧版本兼容兜底字段，无兼容需求可直接删除
  "types": "./dist/A.d.ts",
  "main": "./dist/A.js",
  "module": "./dist/A.mjs"
}

常见注意事项 #

• 类型文件统一使用 .d.ts 后缀即可，不需要对应JS文件的 .mjs/.cjs 后缀，TypeScript 会自动匹配对应模块格式的类型。
• 除非你刻意给ESM和CJS入口写了两份完全不同的类型声明，否则不需要在 import、require 条件块内单独嵌套 types 配置，直接在入口顶层放 types 就能覆盖99%的单TS源码编译场景。
• 配置完成后可以用本地类型校验工具检查导出配置是否正确，避免发布后出现用户侧找不到类型的问题。

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