TypeScript 项目引用

项目引用（Project References）允许把一个大型 TypeScript 工程拆分成多个"子项目"，每个子项目拥有独立的 tsconfig，并按依赖关系增量构建。它让类型检查范围变小、编译速度更快，是多包工程的基石。

什么是项目引用

一个大型应用可以拆成 core（核心库）、utils（工具）、app（入口应用）等子项目。根目录 tsconfig 通过 references 字段声明它们之间的引用关系：

// tsconfig.json（根）
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/app" }
  ]
}

files 留空表示根配置不编译任何文件，只负责编排各子项目。

子项目需要开启 composite

被引用的子项目必须在 compilerOptions 中设置 composite: true，它隐含开启 declaration，并会生成 .tsbuildinfo 记录构建状态：

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

composite 项目不能用 tsc 单独"整包"增量，必须配合下文构建模式使用。

用 tsc -b 构建

子项目之间互不重复检查，必须用构建模式 tsc -b 代替普通 tsc：

tsc -b            # 按依赖顺序构建所有被引用的项目
tsc -b -w         # 监听模式，任一项目改动自动重建
tsc -b --clean    # 删除所有子项目的构建产物

tsc -b 依据 references 自动决定构建顺序：先 core 再 app，且只重建有改动的部分。

跨项目引用示例

在 app 中引用 core 提供的函数，依赖关系通过 app 自身的 references 声明：

// packages/app/tsconfig.json
{
  "references": [{ "path": "../core" }],
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

// packages/core/src/math.ts
export function add(a: number, b: number): number {
  return a + b;
}

// packages/app/src/main.ts
import { add } from "../../core/src/math";

console.log(add(1, 2)); // 输出：3

app 编译时会先构建 core，再读取其产物与声明文件完成类型检查与打包。

小结

项目引用把大工程拆成独立编译的小项目，配合 composite 与 tsc -b 实现按依赖顺序的增量构建。项目越大、拆分越合理，节省的编译时间就越明显。