JavaScript / TypeScript / 系统课时
项目引用与增量构建
项目引用与增量构建
当代码库拆成多个 TypeScript 子项目后,单个 tsconfig.json 往往会让每次编译都扫描过多文件。本篇用 Project References 把依赖关系显式化,并用 tsc -b 让编译器按依赖顺序构建、复用上一次结果。
学习目标
- 理解
references、composite与构建图之间的关系 - 配置一个可运行的两项目引用示例
- 使用
tsc -b验证依赖顺序与增量构建
把代码库变成构建图
项目引用的核心不是“把配置拆成多个文件”,而是让 TypeScript 知道哪个项目依赖哪个项目。根配置负责聚合,真正参与编译的子项目开启 composite,依赖方再通过 references 指向被依赖方。

references 只描述 TypeScript 项目之间的编译依赖,它不会替代 npm workspace、包发布配置或运行时模块解析。大型仓库通常会同时使用包管理器解决包边界,再用 Project References 优化类型检查与构建顺序。
配置复合项目
下面建立 lib 与 app 两个子项目。app 依赖 lib,根配置只负责告诉构建模式从哪些项目开始。
根目录 tsconfig.json:
{
"files": [],
"references": [
{ "path": "./lib" },
{ "path": "./app" }
]
}lib/tsconfig.json:
{
"compilerOptions": {
"composite": true,
"declaration": true,
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true
},
"include": ["./index.ts"]
}lib/index.ts:
export function add(left: number, right: number): number {
return left + right;
}app/tsconfig.json:
{
"compilerOptions": {
"composite": true,
"declaration": true,
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true
},
"include": ["./index.ts"],
"references": [
{ "path": "../lib" }
]
}app/index.ts:
import { add } from "../lib/index.js";
console.log(add(1, 2));composite 让子项目满足可被引用的约束,并要求编译器能够确定项目输入与声明输出。这里显式写出 declaration,是为了让配置意图更清楚;引用方会基于被引用项目的声明信息进行类型检查。
用 build mode 验证增量
项目根目录已安装 TypeScript 后,先清理旧产物,再从根配置执行构建并运行应用:
npx tsc -b --clean
npx tsc -b
node app/index.js预期输出:
3首次 tsc -b 会按依赖顺序先处理 lib,再处理 app,并保存构建元信息。再次执行 npx tsc -b 时,构建模式会检查输入、输出和构建信息;没有失效的项目可以被跳过,因此大型仓库不必每次从头检查所有源码。
需要观察判断过程时,可以临时加上 --verbose;需要删除 Project References 生成的构建产物时使用 tsc -b --clean。这两个命令应针对同一组配置执行,避免把旧产物误认为最新结果。
什么时候值得拆项目
适合使用 Project References 的场景是仓库中已经存在稳定边界,例如共享库、服务端、前端、测试工具各自拥有独立输入与输出,并且它们之间有明确依赖。此时引用图可以缩小单次构建范围,也能阻止子项目无意间吞入边界外源码。
如果代码量很小、模块边界仍频繁变化,过早拆分会增加多个 tsconfig.json、声明输出和依赖维护成本。判断是否值得使用的关键不是“目录够不够多”,而是能否画出稳定的有向依赖图,并让每个节点都可以独立完成类型检查与编译。