多模块TypeScript项目自定义库函数类型声明UI模块失效问题

核心原因 #

• 路径解析错误：你的基础tsconfig.json存放在项目根目录的src文件夹下，files数组里的相对路径默认相对于当前tsconfig.json所在位置解析。而ui目录和src目录平级，当ui下的tsconfig.json继承基础配置时，会把路径解析为ui/src/@types/@company/angular-util/hierarchy-types.types.ts，这个路径实际不存在，所以无法加载自定义类型声明。
• 子配置覆盖：如果ui目录的tsconfig.json中单独配置了typeRoots、files或include字段，会直接覆盖父级的对应配置，不会做合并，导致父级定义的类型文件路径失效。
• 模块声明未合并：你当前的自定义声明没有导入原库的类型，TypeScript会默认你是完全覆写这个模块，而不是合并类型定义，部分场景下会导致类型识别异常。

修复步骤 #

1. 修正路径配置
   方法1：将基础tsconfig.json移动到项目根目录，把files和typeRoots的路径修改为相对于根目录的写法：

   "compilerOptions": {
     "typeRoots": [
       "node_modules/@types",
       "src/@types"
     ],
   },
   "files": [
     "src/@types/@company/angular-util/hierarchy-types.types.ts"
   ]
   

   方法2：在ui目录的tsconfig.json中单独添加正确的类型文件路径：

   "files": [
     "../src/@types/@company/angular-util/hierarchy-types.types.ts"
   ],
   "include": [
     "src/**/*",
     "../src/@types/**/*"
   ]
   

2. 修正模块声明写法
   给自定义类型声明文件添加原库类型导入，确保是类型合并而非覆写：

   // 先导入原模块的基础类型
   import type { PropertyGroup, Property } from '@company/angular-util';
   // 再导入你自定义的枚举
   import type { MyKeyEnum, MyPathEnum } from '你的枚举定义路径';
   
   declare module '@company/angular-util' {
     export function findProperty(propertyGroup: PropertyGroup, type: string, key: MyKeyEnum, path?: MyPathEnum[]): Property<string>;
   }
   

3. 检查子配置冲突
   查看ui目录的tsconfig.json是否有自定义的typeRoots、include配置，如果有，需要把父级的类型路径手动添加到子配置中，避免覆盖失效。
4. 刷新IDE索引
   打开IntelliJ IDEA的 File > Invalidate Caches... 清理缓存并重启，等待索引重建完成后验证类型提示。

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