TypeScript 7 并行编译怎么调：checkers、builders 与 CI 资源预算

TypeScript 7 把编译器和语言服务迁移到 Go 原生实现后，解析、类型检查和输出都可以利用多核并行。官方公布的大型开源项目全量构建数据通常比 TypeScript 6 快 8 到 12 倍，但这不意味着 CI 上把并行数开得越大越好：--checkers 与 --builders 会叠加并发，核数、内存和项目引用图才是最终约束。

先看懂 TypeScript 7 并行发生在哪里

TypeScript 7 并不是只把旧版 tsc 换成一个更快的可执行文件。官方说明中，解析、类型检查和 emit 都能并行处理；其中解析和输出较容易按文件拆开，类型检查则要处理跨文件共享的依赖与全局类型，因此使用固定数量的 checker worker，并让相同输入以确定方式分配。

这一区别很重要：框图中的“源码文件”先进入并行解析，检查结束后再进入“并行输出”。单项目的全量检查主要受 checker 数量影响，而含有大量 project references 的 monorepo 还会受到 builder 数量影响。调参前先确认仓库属于哪一种，否则可能增加了一组对当前命令根本不起作用的参数。

checkers 控制单个项目的类型检查并发

--checkers 的默认值是 4。提高到 8 可能让大型项目更快，但每个 checker 都会承担一部分重复的公共类型工作，因此通常会增加内存消耗；在只有少量 CPU 或内存较紧的 CI runner 上，设为 1 或 2 反而更稳定。

# 建立单线程检查基线
npx tsc --noEmit --checkers 1 --extendedDiagnostics

# 与默认并行度比较
npx tsc --noEmit --checkers 4 --extendedDiagnostics

# 仅在机器资源充足时继续试验
npx tsc --noEmit --checkers 8 --extendedDiagnostics

三次测试要使用同一份依赖、同一提交和同一种冷启动或热启动条件，并同时记录总耗时、峰值内存及失败率。不要把官方项目的倍数直接当成自己的预期：项目规模、类型复杂度、CPU 配额和容器内存上限都会改变结果。

builders 只解决项目引用图的并行

执行 tsc -b 时，--builders 控制同时构建多少个 project reference。它能否带来收益取决于引用图：如果所有项目排成一条依赖链，后一个必须等待前一个，增加 builder 也无法跳过依赖；如果有多个互不依赖的叶子项目，才有更多并行空间。

# 适合先在受限 CI 上采用的保守组合
npx tsc -b --checkers 2 --builders 2

# 资源充足且引用图存在并行分支时再测试
npx tsc -b --checkers 4 --builders 4

第二组参数不是“4 个并发任务”，而是每个并行 builder 最多又可调度 4 个 checker，因此图中的资源上限写作“最多 16 个类型检查器”。容器只分配 4 核或内存余量很小时，这种组合可能造成争抢、交换或被 OOM 终止。

singleThreaded 用于把并发变量排除掉

--checkers 1 只把类型检查限制为单 worker，解析和输出仍可能并行。若要排查偶发差异、与外部并行构建器对照，或者在资源极小的环境中彻底关闭编译器内部并行，应使用 --singleThreaded：

npx tsc --noEmit --singleThreaded --extendedDiagnostics

它更适合作为诊断基线。如果单线程稳定而高并行配置频繁失败，下一步应检查容器 CPU 限额、峰值内存和外层 CI 是否已经并行执行多个包，而不是立即把问题归因于类型系统。

一套可落地的 CI 调参顺序

1. 固定环境：锁定 TypeScript 7 版本、依赖锁文件、提交和 runner 规格。
2. 建立基线：先跑 --singleThreaded 或 --checkers 1，记录耗时与峰值内存。
3. 只改一个参数：单项目先测试 checker；项目引用仓库确认引用图后再增加 builder。
4. 观察乘法并发：把 checkers × builders 写进流水线备注，避免与矩阵任务、包管理器并行叠加。
5. 设回退阈值：若峰值内存逼近容器上限、耗时反而上升或出现偶发失败，就退回上一档。
6. 固定生产值：开发机与 CI 可以使用不同参数，但同一类 runner 应保持一致，避免结果受资源漂移影响。

采用前还要确认工具链边界

TypeScript 7.0 本身不提供稳定的编程 API。依赖 typescript API 的工具可以暂时使用官方的 @typescript/typescript6 兼容包与 7.0 命令行并存。Vue、Svelte、Astro、MDX 等把 TypeScript 嵌入自身语言服务的工作流，也可能暂时继续依赖 6.0；不能只看到 tsc 加速，就默认整个编辑器和插件链都已经完成切换。

此外，--checkers 与 --builders 在 7.0 中仍属于实验控制项。把它们固定进生产流水线前，应保留默认参数的对照任务，并在升级 TypeScript 小版本后重新测量。

常见问题

8 核 runner 就应该设置 checkers 8 吗？

不一定。checker 会重复部分公共类型工作，更多 worker 往往需要更多内存；还要给包管理器、测试和同机其他任务保留资源。

普通 tsc 命令需要设置 builders 吗？

通常不需要。builders 面向 tsc -b 的 project references 构建，单项目编译主要测试 checkers 即可。

checkers 1 与 singleThreaded 有什么区别？

--checkers 1 只限制类型检查 worker；--singleThreaded 还会让解析和输出进入单线程，诊断范围更彻底。

为什么并行度增加后反而更慢？

常见原因是 CPU 配额不足、内存带宽争抢、外层任务已经并行，或者项目引用图没有足够独立分支。应回看 CPU、内存和任务时间线，而不是继续加数字。

结语

TypeScript 7 的原生并行编译为大型项目带来了明显空间，但最佳参数来自自己的项目和 runner。先用单线程建立可复查基线，再分别调整 checkers 与 builders，并始终按两者乘积估算上限，才能把编译提速变成稳定收益，而不是新的 CI 资源波动。