[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 types 编译选项, TypeScript 中的全局声明与全局扩展

TypeScript 中的 typeRoots

一句话定义

typeRoots 用来限制 TypeScript 只从哪些目录里自动收集类型包。

核心机制 / 工作原理

官方文档说明，默认情况下 TypeScript 会把所有“可见”的 @types 包都纳入 compilation。

例如父级目录中的：

• ./node_modules/@types
• ../node_modules/@types
• ../../node_modules/@types

都可能被视为可见。

如果配置：

{
  "compilerOptions": {
    "typeRoots": ["./typings", "./vendor/types"]
  }
}

那么 TypeScript 只会从这些目录里加载类型包，而不会再去自动扫描默认的 node_modules/@types。

最小例子 / 最小场景

显式限定类型包来源

{
  "compilerOptions": {
    "typeRoots": ["./typings"]
  }
}

这常见于：

• 有一批自定义全局声明目录
• 想隔离自动注入的第三方类型
• monorepo 中需要更强的类型边界控制

边界与易混淆点

它和 types 不同

两者都在控制“自动进来的类型环境”，但粒度不同：

• typeRoots 控制去哪些目录找类型包
• types 控制具体启用哪些包名

也就是说：

• typeRoots 更像控制搜索范围
• types 更像控制允许名单

一旦写了 typeRoots，默认 @types 自动发现就不再生效

这是它最容易踩坑的地方。

如果你手动指定了 typeRoots，却没有把真正需要的类型目录包含进去，就会出现：

• process 突然不存在
• 测试全局类型消失
• 某些第三方类型不再可见

它不是给普通源码 alias 用的

typeRoots 管的是类型包目录，不是：

• src 源码路径映射
• import alias

那些仍然更接近：

• paths
• baseUrl

参考信息

• TSConfig typeRoots: https://www.typescriptlang.org/tsconfig/typeRoots.html