如何在package.json中组合子路径导出、环境与模块系统条件导出？

要同时实现子模块导出、根据消费者的包加载器/环境提供对应文件，并且兼容TypeScript类型，核心是在package.json的exports字段中嵌套组合子路径、模块系统条件、环境条件，同时配置TypeScript的类型声明映射。

1. 完整的package.json配置示例 #

{
  "name": "my-package",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "import": {
        "node": "./dist/esm/node/index.js",
        "browser": "./dist/esm/browser/index.js",
        "default": "./dist/esm/index.js"
      },
      "require": {
        "node": "./dist/cjs/node/index.js",
        "browser": "./dist/cjs/browser/index.js",
        "default": "./dist/cjs/index.js"
      }
    },
    "./utils": {
      "types": "./dist/types/utils.d.ts",
      "import": {
        "node": "./dist/esm/node/utils.js",
        "browser": "./dist/esm/browser/utils.js",
        "default": "./dist/esm/utils.js"
      },
      "require": {
        "node": "./dist/cjs/node/utils.js",
        "browser": "./dist/cjs/browser/utils.js",
        "default": "./dist/cjs/utils.js"
      }
    },
    "./components/Button": {
      "types": "./dist/types/components/Button.d.ts",
      "import": {
        "node": "./dist/esm/node/components/Button.js",
        "browser": "./dist/esm/browser/components/Button.js",
        "default": "./dist/esm/components/Button.js"
      },
      "require": {
        "node": "./dist/cjs/node/components/Button.js",
        "browser": "./dist/cjs/browser/components/Button.js",
        "default": "./dist/cjs/components/Button.js"
      }
    }
  },
  "typesVersions": {
    "*": {
      "utils": ["./dist/types/utils.d.ts"],
      "components/Button": ["./dist/types/components/Button.d.ts"]
    }
  }
}

2. 配置要点解释 #

子路径导出（Subpath Exports） #

• 通过exports中的./utils、./components/Button等键，定义可直接导入的子模块路径，消费者可以通过import { xxx } from 'my-package/utils'或const { xxx } = require('my-package/utils')导入。
• 子路径必须以./开头，不能使用绝对路径或裸路径。

模块系统条件导出 #

• 每个子路径下通过import和require字段，分别为ES Modules和CommonJS加载器提供对应的构建文件：
  • import字段对应使用import语法的ES模块环境
  • require字段对应使用require()的CommonJS环境

环境条件导出 #

• 在import/require字段下嵌套node、browser等环境条件，为不同运行环境提供针对性的文件：
  • node：针对Node.js环境的构建产物
  • browser：针对浏览器环境的构建产物
  • default：作为 fallback，当没有匹配到指定环境时使用

TypeScript类型兼容 #

• 在每个导出路径下添加types字段，指定该路径对应的类型声明文件，确保TypeScript能正确识别子模块的类型。
• 配置typesVersions字段，为旧版本TypeScript（不支持exports中的types条件的版本）提供类型映射，保证向下兼容。

3. 配套的TypeScript编译配置（tsconfig.json） #

确保tsconfig.json中开启类型声明输出，并配置正确的模块解析策略：

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./dist/types",
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "target": "ES2020"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

• declaration: true：自动生成类型声明文件
• declarationDir：指定类型文件输出到dist/types目录，与package.json中的types路径对应
• moduleResolution: "NodeNext"：支持Node.js的模块解析策略，兼容exports字段的条件导出逻辑

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