JavaScript / TypeScript / 系统课时

项目引用与增量构建

项目引用与增量构建

当代码库拆成多个 TypeScript 子项目后,单个 tsconfig.json 往往会让每次编译都扫描过多文件。本篇用 Project References 把依赖关系显式化,并用 tsc -b 让编译器按依赖顺序构建、复用上一次结果。

学习目标

  • 理解 references、composite 与构建图之间的关系
  • 配置一个可运行的两项目引用示例
  • 使用 tsc -b 验证依赖顺序与增量构建

把代码库变成构建图

项目引用的核心不是“把配置拆成多个文件”,而是让 TypeScript 知道哪个项目依赖哪个项目。根配置负责聚合,真正参与编译的子项目开启 composite,依赖方再通过 references 指向被依赖方。

TypeScript 项目引用与增量构建图

references 只描述 TypeScript 项目之间的编译依赖,它不会替代 npm workspace、包发布配置或运行时模块解析。大型仓库通常会同时使用包管理器解决包边界,再用 Project References 优化类型检查与构建顺序。

配置复合项目

下面建立 lib 与 app 两个子项目。app 依赖 lib,根配置只负责告诉构建模式从哪些项目开始。

根目录 tsconfig.json:

json
{
  "files": [],
  "references": [
    { "path": "./lib" },
    { "path": "./app" }
  ]
}

lib/tsconfig.json:

json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  },
  "include": ["./index.ts"]
}

lib/index.ts:

ts
export function add(left: number, right: number): number {
  return left + right;
}

app/tsconfig.json:

json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  },
  "include": ["./index.ts"],
  "references": [
    { "path": "../lib" }
  ]
}

app/index.ts:

ts
import { add } from "../lib/index.js";

console.log(add(1, 2));

composite 让子项目满足可被引用的约束,并要求编译器能够确定项目输入与声明输出。这里显式写出 declaration,是为了让配置意图更清楚;引用方会基于被引用项目的声明信息进行类型检查。

用 build mode 验证增量

项目根目录已安装 TypeScript 后,先清理旧产物,再从根配置执行构建并运行应用:

bash
npx tsc -b --clean
npx tsc -b
node app/index.js

预期输出:

text
3

首次 tsc -b 会按依赖顺序先处理 lib,再处理 app,并保存构建元信息。再次执行 npx tsc -b 时,构建模式会检查输入、输出和构建信息;没有失效的项目可以被跳过,因此大型仓库不必每次从头检查所有源码。

需要观察判断过程时,可以临时加上 --verbose;需要删除 Project References 生成的构建产物时使用 tsc -b --clean。这两个命令应针对同一组配置执行,避免把旧产物误认为最新结果。

什么时候值得拆项目

适合使用 Project References 的场景是仓库中已经存在稳定边界,例如共享库、服务端、前端、测试工具各自拥有独立输入与输出,并且它们之间有明确依赖。此时引用图可以缩小单次构建范围,也能阻止子项目无意间吞入边界外源码。

如果代码量很小、模块边界仍频繁变化,过早拆分会增加多个 tsconfig.json、声明输出和依赖维护成本。判断是否值得使用的关键不是“目录够不够多”,而是能否画出稳定的有向依赖图,并让每个节点都可以独立完成类型检查与编译。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目引用与增量构建

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通