自定义NPM包中类型声明文件无法找到的问题排查

我之前也碰到过类似的私有类型包拆分后无法被识别的情况，结合你的场景，问题主要出在TypeScript对自定义私有包的类型加载逻辑以及包本身的配置上，下面是具体的排查和解决步骤：

1. 确保类型包（project-b）的package.json配置正确 #

TypeScript不会自动扫描node_modules里所有的.d.ts文件，它会优先读取每个包的package.json里的types（或typings）字段来找到类型入口。所以你需要在@company-a/project-b的package.json里添加这个字段：

{
  "name": "@company-a/project-b",
  "types": "index.d.ts",
  // 其他配置...
}

如果你的package-name.d.ts没有被index.d.ts引用，还需要在index.d.ts里通过引用指令包含它：

/// <reference path="./package-name.d.ts" />

这样当TypeScript加载project-b的类型时，会自动包含@company-b/package-name/module-name的模块声明。

2. 调整project-a的tsconfig.json配置 #

你之前配置的typeRoots可能不太准确，typeRoots主要是用来指定@types/*这类全局类型包的根目录，对于自定义的私有包，TypeScript会通过常规的模块解析逻辑去查找。

方案一：移除不必要的typeRoots配置（推荐） #

如果project-b的package.json已经正确配置了types字段，TypeScript会自动在node_modules/@company-a/project-b下找到类型入口，此时你可以简化compilerOptions：

{
  "compilerOptions": {
    "typeRoots": [ "./node_modules/@types" ], // 保留默认的@types目录即可
    "moduleResolution": "node" // 确保模块解析策略为node，默认就是这个，但可以显式指定
  }
}

方案二：如果方案一不生效，调整typeRoots指向父目录 #

如果TypeScript还是没识别到，你可以把typeRoots指向@company-a目录，让它扫描这个目录下的所有包：

{
  "compilerOptions": {
    "typeRoots": [ "./node_modules/@types", "./node_modules/@company-a" ]
  }
}

3. 确保project-a的include字段覆盖类型包（可选） #

如果上述配置还是不行，你可以在project-a的tsconfig.json里显式包含project-b的类型文件，强制TypeScript加载它们：

{
  "include": [
    "src/**/*",
    "./node_modules/@company-a/project-b/**/*.d.ts"
  ]
}

4. 验证模块解析逻辑 #

你可以通过TypeScript的--traceResolution参数来排查类型查找过程，在project-a的根目录运行：

tsc --traceResolution

这个命令会输出TypeScript查找每个模块的详细过程，你可以从中看到它有没有尝试加载@company-a/project-b里的类型文件，以及哪里出了问题。

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