如何将多个TypeScript声明文件打包进npm包并从index.d.ts导入？

问题根源 #

CRA的构建流程（基于webpack）会解析代码中的导入语句，但.d.ts类型文件不属于可执行代码，webpack无法找到对应的JS模块，因此直接在index.ts中导入.d.ts文件会导致构建报错。同时，错误的类型入口配置会导致部分类型无法被识别。

解决方案 #

1. 规范类型文件的模块结构 #

确保types/目录下的每个.d.ts文件都是ES模块（包含export）；如果是命名空间类型，也需要通过导出暴露：

// types/type1.d.ts
// 普通类型导出示例
export type SomeType1 = {
  id: string;
};

// 命名空间导出示例
declare namespace MyNamespace1 {
  interface Config {
    name: string;
  }
}
export = MyNamespace1;
export as namespace MyNamespace1;

2. 调整根目录index.ts的导出逻辑 #

使用import type导入类型（编译为JS时会被移除，避免webpack解析），同时导出工具函数和所有类型：

// index.ts
// 导入并导出工具函数
export { someUtility } from './src/someUtilities';

// 导入并导出普通类型
import type { SomeType1 } from './types/type1';
import type { SomeType2 } from './types/type2';
export type { SomeType1, SomeType2 };

// 导入并导出命名空间类型（如果有）
import type * as MyNamespace1 from './types/type1';
import type * as MyNamespace2 from './types/type2';
export { MyNamespace1, MyNamespace2 };

3. 配置package.json的核心字段 #

确保类型入口和代码入口指向根目录的编译产物，同时指定打包时需要包含的文件：

{
  "main": "./index.js",
  "types": "./index.d.ts",
  "files": [
    "index.js",
    "index.d.ts",
    "src/**/*.js",
    "types/**/*.d.ts"
  ]
}

4. 修正tsconfig.json编译配置 #

开启声明文件生成，并确保包含所有需要编译的文件：

{
  "compilerOptions": {
    "declaration": true, // 生成声明文件
    "declarationMap": false, // 可选，关闭声明映射减少体积
    "target": "ESNext",
    "module": "CommonJS",
    "outDir": "./", // 编译产物输出到根目录（可按需调整）
    "strict": true
  },
  "include": ["src/**/*", "types/**/*", "index.ts"],
  "exclude": ["node_modules"]
}

5. 打包并测试 #

执行tsc编译后，用npm pack生成tgz包，在CRA项目中安装后：

• 开发时VSCode可正常从myPackage根路径导入所有类型和函数
• 执行npm run build时，webpack不会解析类型导入，因此不会出现模块找不到的报错

为什么之前的方法无效？ #

• 直接导入.d.ts文件：webpack会将其视为普通模块，但无法找到对应的JS文件，导致构建报错
• 指定types为types/index.d.ts：仅会加载该文件的类型，无法包含src目录工具函数的类型
• 使用三斜线指令：属于全局类型引用，不会将类型导出到包的根模块，因此需要完整路径导入

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