[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 outDir, TypeScript 中的 composite
• 相关实践: Monorepo 中的 tsconfig 实践

TypeScript 中的 rootDir

一句话定义

rootDir 用来告诉 TypeScript：哪些源码目录应被视为输出目录结构的共同根。

核心机制 / 工作原理

TypeScript 在 emit 时会尽量保留输入目录结构。rootDir 决定的是：

• 输出目录结构从哪里开始截取
• 哪些文件被认为在“项目源代码根”之内

例如：

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

配合：

src/
  api/index.ts

通常会输出成：

dist/
  api/index.js

最小例子 / 最小场景

常见搭配

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

这是单包项目里最常见的组合。

典型报错

如果一个被编译文件跑到了 rootDir 之外，TypeScript 常见会报：

• TS6059

这通常意味着：

• include 范围太大
• paths 把别的源码拉进来了
• monorepo 里跨包直接连到了别人的 src

边界与易混淆点

rootDir 不决定哪些文件被纳入 program

真正决定 program 边界的仍然是：

• files
• include
• exclude
• 以及 import 链本身

rootDir 更像是在这些文件已经被纳入之后，告诉 TypeScript 应该如何组织输出路径。

rootDir 常和 composite 互相影响

官方文档说明：如果启用了 composite 且没有显式指定 rootDir，默认值会变成 tsconfig.json 所在目录。

因此在 monorepo 或 project references 场景里，显式写出 rootDir 往往更清楚。

参考信息

• TSConfig rootDir: https://www.typescriptlang.org/tsconfig/#rootDir
• TSConfig composite: https://www.typescriptlang.org/tsconfig/composite.html