你正美滋滋地跑着 npx turbo build,眼看着页面一个个编译完,突然笔记本没电了。等你插上电源重新打开终端,信心满满地再敲一次命令,结果 Turborepo 像失忆了一样,开始从头把每一个包又重新编译一遍。那种感觉就像刚拖好的地被人踩了一圈脚印,很难受。

这个场景我在很多 Monorepo 项目里都见过。今天就聊一聊:为什么中断之后 Turbo 会重复构建,以及怎么把它治好。

一、先看这个让人抓狂的场景

假设你的仓库里有 ui、utils、app 三个包。第一次跑构建的时候,你看到终端里类似这样的输出:

# 第一次构建
utils#build: cache miss, running...
ui#build: cache miss, running...
app#build: cache miss, running...

结果中途你按了 Ctrl+C,或者电脑当场死机。等你重新运行构建时,终端里往往是这个样子:

# 第二次构建
utils#build: cache miss, running...
ui#build: cache miss, running...
app#build: cache miss, running...

明明源码一个字都没动,为什么全都要重新来一遍?这不是你的错觉,也不是 Turborepo 脑子坏了,而是“中断”这件事本身破坏了它赖以信任的规则。

二、Turborepo 的缓存到底认什么账

Turborepo 跟很多构建工具一样,靠缓存来跳过那些“输入没变化”的任务。但这个缓存不是项目级的,它是任务级的。

2.1 缓存是任务级,不是项目级

Turborepo 会把每一个包里的每一个任务(比如 build、test)单独计算一个指纹。这个指纹由下面这些东西拼出来:

  • 这个任务本身的配置
  • 这个包里的源文件内容
  • 它依赖的其他任务的指纹
  • 声明的 inputs 文件变化

只有当任务完整成功地跑完,Turborepo 才敢把结果收进缓存抽屉。如果任务正在运行中,突然断了电或者被强杀,那这个任务就没有资格进抽屉。就算 dist 目录里已经躺着各种文件,Turborepo 也假装没看见,因为它不敢确认那些文件是不是完整的。

2.2 中断的“半成品”会污染下一轮输入

还有一个更隐蔽的问题:如果你没有把输出目录正确隔离,中断留下的半成品会被当成下一轮构建的“输入”。Turborepo 在计算指纹的时候,如果发现 dist 目录突然多出一些乱七八糟的文件,它会觉得“你的环境变了”,于是指纹对不上,缓存直接失效。

这就好比你去食堂打饭,原本只要刷一次卡。结果你上一次饭没打完就走了,饭碗里剩了一半,下一次再去打饭,机器看到你碗里还有剩饭,觉得你是一个新的人,又让你刷一次卡。气不气?

三、先把 Turborepo 的配置收拾干净

要解决这个问题,第一步不是写复杂脚本,而是把 turbo.json 里的 inputs 和 outputs 配对。很多项目重复构建,就是因为这里没配好。

下面是一个很稳的基础配置:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**"]
    }
  }
}

这段配置的意思是:

  • inputs:只有 src、package.json、tsconfig.json 这些文件参与指纹计算
  • outputs:构建完成后的 dist 目录是缓存产物,同时也被排除在输入指纹外

这样,只要源码没变,哪怕你上一次构建只跑了一半,残留的 dist 也不会影响下一次判断。

3.1 不要乱写 inputs

有些人图省事,会写成像这样:

{
  "tasks": {
    "build": {
      "inputs": ["src/**", "dist/**"],
      "outputs": ["dist/**"]
    }
  }
}

这等于自己给自己挖坑。dist 本来就是输出,你又把它写进输入,那中断后的半成品必然会让缓存失效。记住:输出目录永远不要放进 inputs。

3.2 别忘了 .gitignore

还要保证 dist 和临时目录都被 .gitignore 忽略,否则某些场景下 Turborepo 会把它们纳入文件监控,增加不必要的干扰。比如:

# 忽略所有构建产物
dist/
.tmp-build/

这不是玄学,是为了让构建系统清清楚楚地知道:哪些是输入,哪些只是垃圾。

四、给构建脚本加上“原子输出”

配置改好以后,我们还需要处理另一个问题:中断的那一瞬间,正在写的输出文件没有被完整保存。下一次构建时,这个任务还是会重跑。为了把这个“必须重跑”的范围压到最小,我们可以把构建脚本改成“原子输出”模式。

说人话就是:先把构建产物写到临时目录,等所有事情都成功了,再一次性把临时目录改成正式的 dist 目录。这样中断发生时,正式目录里不会残留半成品,下一次构建时,Turborepo 看到一个干干净净的环境,就能放心跳过其他缓存命中的任务。

下面所有脚本都用 Node.js + JavaScript(ESM)来写,命令只是用来跑这些脚本。先看核心的 safe-build.mjs:

// scripts/safe-build.mjs
// 一套用 Node.js 实现的“原子构建”包装器
import { build } from 'esbuild'; // 这里用 esbuild 举例子,实际工具可以换成别的
import { mkdirSync, mkdtempSync, renameSync, rmSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { cwd } from 'node:process';

const root = cwd();                // 当前包根目录
const tempRoot = join(root, '.tmp-build'); // 临时目录统一放在包根目录下
const finalOut = join(root, 'dist');       // 最终的输出目录

// 先清掉上次中断留下的临时目录,避免脏数据干扰指纹
if (existsSync(tempRoot)) {
  rmSync(tempRoot, { recursive: true, force: true });
}
mkdirSync(tempRoot, { recursive: true });

// 生成一个带随机后缀的临时目录,例如 .tmp-build/dist-abc123
const tempOut = mkdtempSync(join(tempRoot, 'dist-'));

// 真正的构建内容:全部写到临时目录,而不是直接写 dist
await build({
  entryPoints: [join(root, 'src/index.ts')], // 入口文件
  outdir: tempOut,                           // 输出到临时目录
  bundle: true,
});

// 只有走到这里,才允许把临时目录切换成正式的 dist
if (existsSync(finalOut)) {
  rmSync(finalOut, { recursive: true, force: true });
}
renameSync(tempOut, finalOut);

然后在 packages/app/package.json 里这样调用:

{
  "name": "@mono/app",
  "type": "module",
  "scripts": {
    "build": "node ../../scripts/safe-build.mjs"
  }
}

这样改完以后,即使你的 esbuild 正在编译时突然断电,顶多只剩一个 .tmp-build 临时目录,不会污染 dist。下次再跑,只有这个被中断的任务需要重新编译,其他已经完整跑完的任务都能用缓存。

五、写一个断点检查员脚本

有时候你并不知道上一次中断到底影响了哪些包。别着急,Turborepo 提供了一个特别好用的预演命令:--dry=json。它不会真的执行构建,而是把每一个任务的缓存状态先列出来。

我们写一个检查脚本,跑完就能看到谁该重跑,谁可以躺平:

// scripts/check-recovery.mjs
// 运行:node scripts/check-recovery.mjs
import { execSync } from 'node:child_process';

// 让 turbo 输出 JSON 格式的预演计划,注意这里不会真的构建
const output = execSync('npx turbo run build --dry=json', { encoding: 'utf8' });
const data = JSON.parse(output);

const missTasks = data.tasks.filter(t => t.cacheState === 'MISS');
const hitTasks = data.tasks.filter(t => t.cacheState === 'HIT');

console.log('可以直接用缓存的:');
for (const t of hitTasks) {
  console.log(`  ${t.taskId} (hash: ${t.hash})`);
}

console.log('需要重新构建的:');
for (const t of missTasks) {
  console.log(`  ${t.taskId} (hash: ${t.hash})`);
}

// 如果发现有任务的缓存状态反复是 MISS,先检查它的 outputs 是不是包含了 dist
// 然后回过头修改 turbo.json 里的 inputs 配置
const suspicious = missTasks.filter(t => t.outputs.some(o => o.includes('dist')));
if (suspicious.length > 0) {
  console.log('提醒:存在 dist 相关 outputs 的任务,请确认 inputs 没有包含 dist/**');
}

实际使用的时候,你只需要先跑一下这个脚本,然后根据提示调整配置,最后正常执行 npx turbo run build 就行。Turborepo 会自动跳过缓存命中的任务,不需要加 --force 把辛苦攒下来的缓存全毁了。

六、这个方案适合用在什么场景

这套“正确配置 + 原子输出 + 断点检查”的组合,特别适合下面几种情况:

  • 大型 Monorepo:包很多,构建时间很长,中断一次损失太大。
  • 本地开发:经常要切分支、重启电脑、不小心按到 Ctrl+C。
  • CI 环境:比如云上构建机突然被回收,或者网络抖动导致远端缓存拿不到。
  • 边缘设备构建:设备性能弱,内存小,构建又慢,中断概率高。

在这些场景里,哪怕你没法保证构建过程不被打断,也能保证打断之后恢复的速度最快。

七、优点、缺点和要注意的坑

7.1 优点

  • inputs 和 outputs 配好后,缓存命中率会提高很多。
  • 原子输出让半成品不会污染正式目录,下一次构建时环境更干净。
  • 断点检查脚本让你随时知道哪些任务在重复构建,不用瞎猜。
  • 整个方案不需要换构建工具,也不依赖特定的服务器。

7.2 缺点

  • 需要改每个包的构建脚本,工程里如果包特别多,初期改造会有一点工作量。
  • 原子输出里删除旧 dist 和重命名之间有一个很小的窗口,极端情况下还是可能中断。
  • 如果构建工具本身把输出路径写死,比如强制要求只能输出到 dist,那这套方式就需要额外绕路。

7.3 注意事项

  • 同一个包不要同时跑两个会写入同一临时目录的任务,否则会互相踩脚。建议临时目录用随机后缀,就像示例里的 mkdtempSync。
  • 记得把 .tmp-build 加进 .gitignore,不然它会污染版本库。
  • 如果你用了远程缓存,也要保证远程缓存的 key 和本地配置一致,否则远程缓存也救不了你。
  • 不要轻易用 --force,这个参数会强制无视缓存,适合排查问题,不适合日常构建。

八、总结

Turborepo 不是神仙,它只是尊重规则。只要任务没有完整结束,它就不认账。我们解决重复构建的核心思路很简单:让输出不污染输入,让中断只影响正在跑的那一个任务,然后利用 Turborepo 已有的缓存能力跳过其他任务。

把这三点做好,以后就算再遇到突然断电,你也能笑着重跑一次,而不是眼睁睁看着整个项目从头再来。