TypeScript project references 怎么按依赖顺序清理并重建多个项目

当一个前端仓库拆成 packages/core、packages/ui 和 apps/web 后，最容易出现的麻烦不是“不会写 tsconfig.json”，而是清理和重建顺序靠人记：先删哪个目录、再跑哪个项目，稍不注意就会读到旧的声明文件。

解决这类问题的关键是把依赖关系写进 references，再让 tsc -b 读取项目图。它会寻找被引用的项目、判断哪些项目已经是最新，并按依赖关系决定构建顺序；命令行上即使把配置路径写乱，也会重新排序。

官方文档：https://www.typescriptlang.org/docs/handbook/project-references

如果多个 TypeScript 项目存在依赖，推荐准备一个只组织引用关系的 solution 配置，然后统一使用 tsc -b、tsc -b --clean 和 tsc -b --verbose。不要把多个项目分别交给 tsc -p，再手动维护顺序。

先看现象：为什么“每个项目都能编译”仍然会出错

假设目录里有三个项目：core 提供类型和基础函数，ui 引用 core，web 再引用 ui。单独执行每个目录的 tsc -p 可能都能通过，但它不会替你维护整个依赖图，也不会自动决定哪些依赖必须先更新。

这时先画出静态关系：web → ui → core。这里的箭头表示“引用关系”，不是某一次命令已经执行的运行结果。后续所有清理和重建操作都应围绕这张关系图展开。

先修配置：被引用项目为什么需要 composite

被其他项目引用的配置必须启用 composite。它让 TypeScript 能快速判断项目输出在哪里，并要求实现文件被 include 或 files 覆盖；同时通常要打开 declaration，因为引用方会使用依赖项目生成的 .d.ts。

例如 packages/core/tsconfig.json 可以先收敛成下面这种边界。JSON 本身不放注释，字段作用写在代码块之后。

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "rootDir": "./src",
    "outDir": "./dist",
    "tsBuildInfoFile": "./dist/.tsbuildinfo"
  },
  "include": ["src"]
}

rootDir 和 outDir 明确了源码与产物边界；declarationMap 便于编辑器跨项目跳转；tsBuildInfoFile 让增量构建状态落在项目自己的输出区域。ui 和 web 也应有各自不重叠的输出目录。

再组织入口：solution tsconfig 只负责 references

仓库根目录的 solution 配置可以不编译源码，只列出需要纳入构建图的项目。把 files 设为空数组，避免 solution 文件又把源码编译一遍。

{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" },
    { "path": "./apps/web" }
  ]
}

每个 path 可以指向包含 tsconfig.json 的目录，也可以直接指向配置文件。真正的先后关系来自各项目内部的 references，而不是这个数组的书写顺序。

例如 packages/ui/tsconfig.json 需要引用核心项目：

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "references": [
    { "path": "../core" }
  ],
  "include": ["src"]
}

这样 web 引用 ui，ui 引用 core，TypeScript 才有足够信息判断依赖项目的声明输出是否需要更新。

动手处理：先预览，再按依赖顺序清理和重建

配置关系明确后，把根目录 solution 配置作为唯一入口。先用 --dry 看 build mode 计划处理哪些项目；它只展示将做什么，不会真正构建。

# 先预览 solution 图涉及的项目，不写入构建产物
tsc -b tsconfig.json --dry

# 清理指定 solution 的构建输出；需要确认范围时先保留 --dry
tsc -b tsconfig.json --clean

# 重新构建过期项目，并打印判断依据
tsc -b tsconfig.json --verbose

--clean 用于删除指定项目的输出，--verbose 会说明项目为什么被跳过或重新构建。清理后首次重建通常会覆盖依赖项目的声明文件和增量状态；后续再次执行时，只有过期项目需要重新编译。

如果希望把所有项目都视为过期，可以使用：

# 强制按项目图重新生成全部输出
tsc -b tsconfig.json --force --verbose

命令行可以同时传入多个配置路径，不必先人工排序；tsc -b 会按引用关系重排。对日常工程来说，一个稳定的 solution 入口更容易复用，也更不容易漏掉依赖。

排查结果：四个配置边界最容易被误判

• 被引用项目没有 composite：先在依赖项目打开 composite，并让实现文件被 include 或 files 覆盖。
• 只写了根配置的 references：根配置列出项目还不够，ui 自己也要引用 core，否则图中缺少真实边。
• 输出目录互相覆盖：为每个项目设置独立的 outDir，必要时显式设置 rootDir，不要让多个项目把产物写到同一层。
• 把 tsc -p 当成 build mode：tsc -p 编译单个配置，不会替你自动构建引用项目；跨项目入口应使用 tsc -b。

最后再运行一次带 --verbose 的构建。如果日志显示依赖项目已是最新而应用项目重新生成，说明项目图和增量判断正在分别发挥作用；如果每次都全量构建，就优先检查 tsBuildInfoFile、输出目录是否被清空，以及版本控制操作是否改变了产物时间戳。

常见问题

references 数组顺序需要手工排列吗？

不需要。真正决定先后的是项目之间的引用关系，tsc -b 会重新排序；但每条依赖边仍要写在被引用项目的配置里。

为什么 clean 后编辑器仍提示类型错误？

引用项目依赖生成的声明文件。清理后先用 solution 配置完成一次 tsc -b，再让编辑器重新读取输出；不要把旧的 dist 文件手工复制回来。

什么时候用 force？

当版本控制或复制过程保留了不可靠的时间戳，导致增量判断不可信时，可以用 --force 让所有项目重新视为过期。日常增量构建不必一直带它。

这套做法的核心不是记住“先编译哪个目录”，而是维护一张准确的项目引用图：项目配置负责描述边界，composite 和声明输出负责提供可消费的接口，tsc -b 再负责按图清理、判断和重建。