TypeScript 大项目提速：从一个 tsconfig 拆到 Project References

什么时候值得拆分

当一次 tsc --noEmit 扫描整个仓库、编辑器跳转明显变慢，或者几个应用共享同一份庞大 include 时，就应该把项目边界显式化。拆分目标不是 tsconfig 数量更多，而是让编译器知道哪些输出可以复用。

应用与共享库可以独立完成类型检查；共享库有稳定的公共类型出口；项目之间的依赖方向清晰；构建系统能缓存每个子项目的产物。

建立引用图

被引用项目需要开启 composite，并为声明文件设置稳定的输出目录。应用项目通过 references 指向共享库，随后使用 tsc -b 让 TypeScript 按拓扑顺序构建。不要让 paths 映射掩盖缺失的项目引用。

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

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist"
  }
}

把提速结果量化

分别记录冷启动构建、无改动重跑和单包修改后的耗时。检查 .tsbuildinfo 是否被 CI 缓存，并确认缓存键包含 TypeScript 版本和锁文件。只看本地第二次运行，很容易高估实际收益。

让 VS Code 使用仓库安装的 TypeScript，避免本地语言服务与 CI 编译器版本不一致。