详解TypeScript项目引用（Project References）中rootDir的坑：composite:true下为何不能指定rootDir

在TypeScript monorepo（多包仓库）开发中，项目引用（Project References）是实现包之间依赖管理、增量构建的核心特性，但很多开发者会遇到「引用外部包时提示文件不在rootDir下」的报错——核心矛盾就是 composite: true 与 rootDir 配置的冲突。本文将从原理到解决方案，彻底讲清楚这个问题。

一、先还原典型报错场景

1. 项目结构（monorepo）

tradeflow/
├── apps/
│   └── b2b-admin/       # 业务项目
│       ├── src/         # 业务源码目录
│       └── tsconfig.json
└── packages/
    └── contract/        # 公共契约包
        ├── src/
        └── tsconfig.json

2. 报错的tsconfig.json（b2b-admin）

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "composite": true,       // 开启项目引用
    "rootDir": "./src",      // 指定源码根目录
    "outDir": "./dist",
    "paths": {
      "@repo/contract": ["../../packages/contract/src"]
    }
  },
  "references": [
    { "path": "../../packages/contract" }  // 引用外部包
  ]
}

3. 核心报错

error TS6059: File 'g:/tradeflow/packages/contract/src/index.ts' is not under 'rootDir' 'g:/tradeflow/apps/b2b-admin/src'. 
'rootDir' is expected to contain all source files.

二、rootDir的本质：不是「项目根目录」，是「源码根目录」

很多开发者误解了 rootDir 的作用——它不是「项目的根目录」，而是 TypeScript 编译器（tsc）认定的「源码根目录」，核心规则：

rootDir 告诉 tsc：「所有需要编译的源文件（.ts/.tsx）必须在这个目录下」；
编译后的输出文件（dist）的目录结构，会严格按照 rootDir 下的结构生成；
若源码文件不在 rootDir 范围内，tsc 会直接报错，拒绝编译。

举个例子：

配置 rootDir: "./src" 后，tsc 只会处理 ./src/**/* 下的文件；
哪怕你在项目根目录下有 ./types.d.ts，只要不在 src 下，tsc 也会忽略（或报错）。

三、composite:true + rootDir 冲突的核心原因

composite: true 是开启「项目引用」的核心配置，它的设计目标是：让多个TypeScript项目（子包）可以互相引用、增量构建。

当同时配置 composite: true 和 rootDir 时，冲突会直接爆发，原因有2点：

1. 项目引用的本质是「跨项目依赖」，但rootDir限制了「源码范围」

项目引用的核心是引用外部项目的源码/编译产物，而 rootDir: "./src" 强制要求「当前项目的所有源码必须在 ./src 下」——但你引用的 @repo/contract 源码在 ../../packages/contract/src，明显不在 b2b-admin/src 范围内，tsc 会判定为「违规」，直接报错。

2. composite模式下，tsc需要「全局视角」，而rootDir是「局部限制」

开启 composite: true 后，tsc 会：

扫描所有被引用的项目（如contract）；
验证这些项目的编译输出、依赖关系；
实现跨项目的增量构建。

但 rootDir 是「局部配置」，它把当前项目的源码范围锁死在 ./src，相当于给 tsc 套了「紧箍咒」——tsc 无法访问外部项目的文件，自然无法完成项目引用的核心逻辑。

简单总结：

配置场景	rootDir 作用	冲突表现
单项目（无composite）	明确源码根目录，规范编译范围	无冲突，是推荐用法
多项目（composite:true）	限制外部文件访问	引用外部包时报「文件不在rootDir下」

四、正确的解决方案（按优先级排序）

方案1：移除rootDir（最推荐）

composite模式下，TypeScript 会自动推断源码根目录，无需手动指定 rootDir——它会扫描当前项目的所有源码文件，同时允许访问被引用项目的文件：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "composite": true,       // 保留项目引用
    // 移除 rootDir 配置
    "outDir": "./dist",
    "paths": {
      "@repo/contract": ["../../packages/contract/src"]
    }
  },
  "references": [
    { "path": "../../packages/contract" }
  ]
}

优势：最简单、符合TypeScript官方推荐，自动适配跨项目引用。

方案2：扩大rootDir范围（不推荐，仅应急）

若因特殊需求必须保留 rootDir，可将其扩大到能覆盖当前项目+被引用项目的目录（仅临时用，会破坏目录规范）：

{
  "compilerOptions": {
    "composite": true,
    "rootDir": "../../",  // 扩大到monorepo根目录
    "outDir": "./dist"
  }
}

弊端：会让tsc编译 ../../ 下的所有文件（包括其他无关项目），增加编译时间，破坏项目隔离。

方案3：通过typeRoots替代（适配类型文件引用）

若只是引用外部包的类型文件，可通过 typeRoots 配置，而非 rootDir：

{
  "compilerOptions": {
    "composite": true,
    "typeRoots": [
      "./src/types",        // 本地类型
      "../../packages/contract/src"  // 外部包类型
    ]
  }
}

五、避坑总结：composite模式的核心配置原则

禁用rootDir：项目引用模式下，让TypeScript自动推断源码根目录，是最安全的选择；
保持composite:true：确保跨项目增量构建、依赖验证正常工作；
用paths映射别名：通过 paths 配置外部包的别名（如 @repo/contract），而非依赖rootDir；
每个子项目独立配置：被引用的包（如contract）也需开启 composite: true，并配置 outDir（输出编译产物）。

六、官方文档佐证

TypeScript官方文档明确说明：

当使用 composite: true 时，建议不要手动指定 rootDir——编译器会自动计算每个项目的根目录，以确保跨项目引用的正确性。若强制指定 rootDir，可能导致引用外部文件时出现路径错误。

最后

TypeScript项目引用的核心是「跨项目协作」，而 rootDir 是「单项目的源码限制」——两者的设计目标本就冲突。在monorepo开发中，遵循「composite模式下移除rootDir」的原则，能避免90%以上的路径/引用报错，同时保证增量构建的效率。