TypeScript无法识别NPM包内自定义第三方类型的问题求助

你遇到的问题本质是：当你的包被安装到消费项目后，TypeScript默认只会读取package.json里types字段指向的自动生成声明文件，以及全局的@types目录，不会主动扫描包内的typings目录。下面给你几个实用的解决方案，按推荐程度排序：

方案1：用typesVersions配置引导TypeScript查找自定义声明 #

这是最简洁且符合TypeScript规范的方式，无需大量修改代码。只需在package.json中添加typesVersions字段，明确告诉TypeScript额外的类型文件位置：

{
  "name": "@dicebear/avatars",
  "version": "2.0.0",
  "main": "lib/index",
  "types": "lib/index",
  "typesVersions": {
    "*": {
      "*": [ "./typings/*", "./lib/*" ]
    }
  }
}

这个配置的含义是：对所有版本的TypeScript，当查找任意类型文件时，优先检查包根目录下的typings目录，再读取lib目录的文件。这样消费项目的TypeScript就能自动识别你自定义的第三方声明了。

方案2：将自定义声明整合到包的类型入口 #

如果你的自定义声明数量不多，可以直接把它们关联到自动生成的声明入口中：

1. 在typings目录下创建一个入口文件index.d.ts，统一引入所有第三方声明：

// typings/index.d.ts
/// <reference path="./package-a.d.ts" />
/// <reference path="./package-b.d.ts" />

2. 在源码入口src/index.ts顶部添加三斜线指令，关联这个声明入口：

// src/index.ts
/// <reference path="../typings/index.d.ts" />

// 你的源码逻辑...

3. 调整tsconfig.json的include数组，把typings目录纳入编译范围：

{
  "compilerOptions": {
    "outDir": "./lib",
    "moduleResolution": "node",
    "declaration": true,
    "noImplicitAny": true,
    "typeRoots": [ "node_modules/@types", "typings" ]
  },
  "include": [ "./src/", "./typings/" ]
}

编译后，自动生成的lib/index.d.ts会间接关联到这些自定义声明，消费项目就能正常识别它们。

方案3：编译时复制自定义声明到lib目录 #

如果你偏好把所有类型文件集中在lib目录，可以在编译脚本中添加复制步骤：

1. 修改package.json的scripts，在tsc编译完成后复制typings目录到lib：

{
  "scripts": {
    "build": "tsc && cp -r typings/ lib/typings/"
  }
}

2. 在自动生成的lib/index.d.ts中添加三斜线指令，引用复制后的声明文件：

// lib/index.d.ts
/// <reference path="./typings/index.d.ts" />

这样消费项目通过types字段指向的入口，就能找到这些自定义声明了。

额外注意事项 #

• 确保你的自定义声明是标准的环境模块格式，比如：

declare module "third-party-package" {
  // 类型定义内容
}

• 不要依赖消费项目的typeRoots配置，你的包应该自身包含所有必要的类型，让消费项目无需额外配置即可正常使用。

内容的提问来源于stack exchange，提问作者Florian Körner