你正美滋滋地跑着 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 已有的缓存能力跳过其他任务。
把这三点做好,以后就算再遇到突然断电,你也能笑着重跑一次,而不是眼睁睁看着整个项目从头再来。
评论
围绕“Turborepo构建中断恢复:解决构建过程意外中断后重复构建的问题”参与讨论