含exports字段的NPM包无法在TypeScript中加载，求排查配置问题

我们的库需要同时支持ESM和CommonJS项目，因此构建了三种配置：ESM、node16（对应CommonJS）、types（生成类型声明）。这套配置在Node.js的JavaScript项目里正常工作，不管是CommonJS还是开启"type": "module"的ESM项目，但在TypeScript项目中使用时，出现错误：

Cannot find module '@ltonetwork/lto' or its corresponding type declarations.

TypeScript配置 #

ESM配置 #

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "lib/esm",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

CommonJS配置 #

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "lib/cjs",
    "module": "node16",
    "moduleResolution": "node16"
  }
}

Types（生成.d.ts文件） #

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "lib/types",
    "declaration": true,
    "module": "node16",
    "moduleResolution": "node16",
    "emitDeclarationOnly": true
  }
}

package.json 配置 #

我们在package.json中通过exports字段指定加载路径：

"exports": {
    ".": {
      "types": "./lib/types/index.d.ts",
      "require": "./lib/cjs/index.js",
      "import": "./lib/esm/index.js",
      "default": "./lib/esm/index.js"
    },
    "./accounts": {
      "types": "./lib/types/accounts/index.d.ts",
      "require": "./lib/cjs/accounts/index.js",
      "import": "./lib/esm/accounts/index.js",
      "default": "./lib/esm/accounts/index.js"
    },
    "./types": "./lib/types/index.d.ts",
    "./constants": "./lib/constants.js",
    "./package.json": "./package.json"
  },

问题原因及修复方案 #

核心问题 #

1. 旧版TypeScript兼容性不足：TypeScript 4.7版本之前对exports字段中的types条件支持不完善，无法正确识别类型声明路径。
2. 类型生成配置与编译产物不匹配：类型生成时使用module: node16，但ESM构建用的是module: ESNext + moduleResolution: bundler，可能导致类型解析时的模块格式冲突。
3. 缺少顶层类型入口：部分TypeScript环境仍依赖package.json顶层的types字段作为类型查找的 fallback，仅通过exports指定可能无法覆盖所有场景。

修复步骤 #

1. 添加顶层types字段

在package.json中添加顶层类型入口，兼容旧版TypeScript：

"types": "./lib/types/index.d.ts",

2. 统一类型生成的模块配置

修改Types配置的module和moduleResolution，使其与ESM/CommonJS的解析逻辑对齐，建议改为NodeNext：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "lib/types",
    "declaration": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "emitDeclarationOnly": true
  }
}

3. 确保类型文件结构与编译产物完全一致

检查lib/types下的文件结构是否和lib/esm、lib/cjs完全对应，确保每个JS文件都有对应的.d.ts文件，避免导入子路径时找不到类型。

4. 建议升级TypeScript版本

推荐使用TypeScript 4.7及以上版本，该版本开始完善支持exports中的types条件，能更好地识别多模块格式的类型声明。

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