tsconfig.json中typeRoots与include处理.d.ts文件的差异及失效原因问询

一、先搞懂俩配置的本质区别 #

• typeRoots：这是专门为第三方类型包（比如node_modules/@types里的结构）设计的加载规则，逻辑很固定：只会识别你指定目录下直接的子文件夹，每个子文件夹会被当作独立的类型包加载。比如你配置了./@types，它只会找./@types/xxx/index.d.ts这种结构；要是你的.d.ts直接扔在@types根目录，或者嵌套了多层子文件夹，它完全识别不到。
• include：这是范围更广的文件匹配配置，只要是通配符匹配到的.ts/.d.ts文件，不管在哪个层级，都会被TypeScript纳入编译和类型检查范围。**通配符就是用来递归扫描所有子目录文件的，所以你加了@types/**/*.ts自然能加载到所有自定义类型。

二、你的typeRoots配置为啥失效 #

你当前的@types目录大概率是直接放.d.ts文件，或者子文件夹没按“类型包”结构来，比如：

@types/
  global.d.ts
  utils.d.ts

这种结构下，typeRoots找不到符合要求的“类型包子文件夹”，自然加载不到你的自定义类型，导致构建报错。

而用include时，@types/**/*.ts会把@types下所有层级的.d.ts都扫一遍，不管文件怎么放都能加载到，所以能正常工作。

三、要想用typeRoots生效，得这么改 #

把@types目录改成“类型包”结构，每个自定义类型单独放在一个子文件夹里，比如：

@types/
  global/
    index.d.ts
  utils/
    index.d.ts

然后保持原来的typeRoots配置不变：

{
  "compilerOptions": {
    "target": "es2020",
    "module": "CommonJS",
    "skipLibCheck": false,
    "typeRoots": ["node_modules/@types", "./@types"],
  },
  "include": [
    "src/**/*.ts", "test/**/*.ts"
  ]
}

这样TypeScript就会把@types下的每个子文件夹当作独立类型包加载，就能识别你的自定义类型了。

四、总结：选哪个配置更合适 #

• 如果你想把自定义类型和第三方类型包的结构对齐，或者需要控制类型加载的优先级，用typeRoots。
• 要是你的自定义类型文件比较零散，不想搞复杂的目录结构，直接用include更省心——不用改文件夹，加一行配置就行。

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