get-shit-done 构建管道原子写入修复实录build-hooks.js 如何终结发布 CI 的并发竞态故障【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done本文以仓库变更集 .changeset/build-hooks-atomic-write.md 为主线还原 get-shit-doneGSD在发布 CI 中遇到的一个典型极难复现故障同一份 hook 产物被多个并发进程同时改写导致安装器读到半截空文件。文章将结合构建脚本 scripts/build-hooks.js、并行测试驱动器 scripts/run-tests.cjs 与回归测试 tests/bug-2136-sh-hook-version.test.cjs 的源码级证据讲透staging 目录 原子 rename这一并发文件写入方案的动机、实现与工程约束。故障现象同一 SHA 在部分矩阵节点上随机性失败修复内容本身很简单——一个type: Fixed的变更PR 3216针对scripts/build-hooks.js引入原子写入。但简单修复的背后是一场典型的发布阻断故障release-blocking failure排查故障只出现在tests/bug-2136-sh-hook-version.test.cjs的part 4端到端安装校验安装出的.shhook 文件丢失了# gsd-hook-version:版本头同一个 commit SHA在其它 Node-22 / Node-24 安装冒烟测试矩阵节点上全部通过唯独这一个节点失败。这类同 SHA 不同节点表现迥异的现象是并发竞态race condition的标志性特征代码本身确定行为却依赖进程间的时序交错。要让这类故障可解释、可复现并彻底修复必须回答三个问题谁在并发写写到了哪里为什么读者会看到半截内容根因分析三个环节叠加出的竞态环节一多个测试文件并行触发同一构建脚本仓库的 hooks 是纯 Node.js / Bash 源文件发布前需由 scripts/build-hooks.js 拷贝到hooks/dist/供安装器分发。而该脚本并非只在发布时执行一次——九个测试文件都在各自的before()钩子中调用它目的是保证任何安装类测试运行前hooks/dist/已被填充。例如 tests/bug-2136-sh-hook-version.test.cjs、tests/bug-1736-local-install-commands.test.cjs、tests/bug-1834-sh-hooks-installed.test.cjs 都采用同一模式const BUILD_SCRIPT path.join(__dirname, .., scripts, build-hooks.js); before(() { execFileSync(process.execPath, [BUILD_SCRIPT], { encoding: utf-8, stdio: pipe, }); });环节二测试驱动器以高并发运行文件九个测试文件要真正并行撞在一起还差最后一块拼图。仓库的跨平台测试驱动器 scripts/run-tests.cjs 在收集并分块测试文件后用如下方式调用 Node 内置测试器const concurrency process.env.TEST_CONCURRENCY ? --test-concurrency${process.env.TEST_CONCURRENCY} : --test-concurrency4;默认的--test-concurrency4意味着多个测试文件在同一个 Node 进程中并行推进。当一个测试文件恰好阻塞在before()里同步执行build-hooks.js先mkdirSync清场再逐文件拷贝时另一个测试文件已经启动真实的bin/install.js安装子进程去读取hooks/dist/了——多 builder 与多 install 读者在同一时间窗口内交错。环节三fs.copyFileSync的截断-写入非原子窗口这才是故障的物理根因。脚本原先以及fs.copyFileSync的语义本身采取的是直接覆盖目标文件的方式其内部等价于先截断truncate目标、再写入新内容。POSIX 层面这并非原子操作因此存在一个真实窗口读者如并行安装测试 spawn 出的bin/install.js子进程恰好在 truncate 与 write 之间执行fs.readFileSync就会观察到内容为空的目标文件。在这个窗口下时序链条是builder A 的fs.copyFileSync(src, dest)执行 truncatehooks/dist/gsd-session-state.sh暂时为空builder B来自另一个测试文件或直接调用安装逻辑的并行安装测试通过readdirSyncreadFileSync读到这份空内容安装器把空内容写入安装目标目录的 hook 文件——于是已安装的.shhook丢失了# gsd-hook-version:版本头后续版本陈旧检测gsd-check-update.js的 stale-hook detector无法读到版本号tests/bug-2136-sh-hook-version.test.cjspart 4 断言失败发布被阻断。需要强调的是问题并非出在安装器逻辑而是构建产物在某个瞬间处于不完整状态。任何基于hooks/dist/的读者都可能命中这个窗口——这正是它难以在干净的矩阵节点上稳定复现的原因。修复方案先落暂存、再原子换名stage atomic rename修复的核心思路是永远不要让读者直接看到正在被写入的目标文件。所有写入先落在同文件系统的暂存区待内容完整后就位后再通过一次原子换名切换进hooks/dist/。读者在任何时刻读到的要么是旧版本完整文件要么是新版本完整文件绝无中间态。scripts/build-hooks.js 中实现为三个关键设计点。设计点一进程专属暂存目录per-PID staging dirconst STAGE_DIR path.join(HOOKS_DIR, .dist-staging-${process.pid});暂存目录名带process.pid每个 builder 进程拥有独立暂存区从根上消除并发 builder 之间在暂存目录创建 / 清理上的竞争——A 进程清理自己目录时绝不会误删 B 进程正在使用的文件。目录被放在hooks/下、hooks/dist/的同级而非内部这同时满足两个约束同文件系统与DIST_DIR共享同一文件系统保证 POSIXrename(2)原子语义成立跨文件系统 rename 会退化为拷贝不在 dist 内部对hooks/dist/执行readdirSync的读者如bin/install.js、各类 install-hooks-copy 测试永远不会观测到临时的.tmp兄弟文件。对应的 gitignore 规则也已落库.gitignore 中同时忽略hooks/dist/与hooks/.dist-staging-*/。设计点二拷贝到暂存 → 修饰 → 原子 rename 就位每个文件的写出流程为见 scripts/build-hooks.js 的 build 主循环const stagedDest path.join(STAGE_DIR, ${hook}.${Date.now()}); fs.copyFileSync(src, stagedDest); // Preserve executable bit for shell scripts before rename so the // installed file is executable from the very first observation. if (hook.endsWith(.sh)) { try { fs.chmodSync(stagedDest, 0o755); } catch (e) { /* Windows */ } } renameAtomicWithRetry(stagedDest, dest, hook);值得注意的细节.sh的chmod 0o755在暂存文件上、rename 之前完成确保安装产物从第一次被观测起就携带可执行位对应历史问题 #1162 的教训。暂存文件名追加Date.now()即使同进程内重复构建也不会碰撞。renameAtomicWithRetry是跨平台的关键封装非 Windows 平台直接走一次fs.renameSyncPOSIXrename(2)原子替换即使读者持有目标文件的打开句柄也能成功Windows 平台则进入重试逻辑详见下文。设计点三Windows 的 EPERM/EBUSY 重试与降级POSIX 的rename(2)允许原子替换甚至正在被读取的目标文件但 Windows 上fs.renameSync底层使用的MoveFileEx(MOVEFILE_REPLACE_EXISTING)做不到——当目标文件被其它进程以打开句柄占用时会抛出EPERM/EBUSY。并发中的install.js读者与杀毒软件扫描是现实中最常见的触发源。实现据此给出了完整的分级策略const BACKOFFS_MS [10, 30, 90, 270];退避重试捕获EPERM/EBUSY后按 10 / 30 / 90 / 270 ms 指数退避重试最多 4 次。句柄通常在毫秒级被释放短退避即可化解退避总计最坏约 400ms对一次性构建脚本可接受拷贝降级重试耗尽后回退为copyFileSync覆盖对该单文件重新引入截断-写入窗口但保住构建不崩并打印黄色警告同时清理暂存文件保留旧产物若拷贝也因目标被硬锁定失败则仅记录非致命警告并保留原有目标文件——下一次构建调用会从全新状态重试。由于脚本端到端为同步执行退避不能用setTimeout而是用Atomics.wait在一个一次性SharedArrayBuffer上实现同步毫秒睡眠见 scripts/build-hooks.js 中的sleepSync。配套的产物拷贝范围本次改造保留并顺带巩固了构建脚本的既有职责HOOKS_TO_COPY清单覆盖 12 个官方 JS/Bash hook 与 1 个 opt-in 的 graphify 自动更新 hookscripts/build-hooks.js 中的清单与说明并通过HOOKS_SUBDIRS_TO_COPY [lib]将hooks/lib/下的附属 helper如gsd-graphify-rebuild.sh一并镜像进 dist使独立运行的 helper 能从安装后的运行时路径正确解析。JS 文件在拷贝前一律经vm.Script做语法预检对应历史问题 #1107/#1109/#1125/#1161——曾有重复const声明流入 dist 导致所有用户 PostToolUse hook 报错任何SyntaxError都会令构建以退出码 1 终止。每个 JS 文件路径都走同一个暂存→rename通道因此原子化保障覆盖全部产物。为什么这一处小改动关乎安装正确性要理解空文件为何会造成安装出的 hook 缺版本头这种看似无关的症状需要把 hook 版本机制这条链路串起来。三个.shhookgsd-phase-boundary.sh、gsd-session-state.sh、gsd-validate-commit.sh以及后来的gsd-graphify-update.sh的源文件中第二行都写有占位符例如 hooks/gsd-session-state.sh#!/usr/bin/env bash # gsd-hook-version: {{GSD_VERSION}}安装器 bin/install.js 在把 hook 拷贝到用户配置目录时对.sh分支必须先readFileSync再做模板替换再writeFileSync把{{GSD_VERSION}}替换为package.json中的真实版本号} else if (entry.endsWith(.sh)) { let content fs.readFileSync(s, utf8); content content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version); fs.writeFileSync(d, content); try { fs.chmodSync(d, 0o755); } catch (_) { /* Windows */ } }一旦构建产物是空文件这一替换读到的就是空字符串写出的安装文件自然没有# gsd-hook-version:头。于是会话开始即提示 stale hooks的假警报出现因为陈旧检测正则(?:\/\/|#) gsd-hook-version:\s*(.)匹配不到版本号会把 hook 判定为hookVersion: unknown。回归保障既有测试如何锁死修复不变量这次修复最有价值的一点在于核心回归保障早已存在无需新写测试。变更说明明确指出tests/bug-2136-sh-hook-version.test.cjs 的 part 4 已经锁死了修复后的不变量。该文件的四个部分恰好覆盖整条链路part 1三个.sh源文件必须携带# gsd-hook-version: {{GSD_VERSION}}占位符且位于 shebang必须为 PATH 解析的#!/usr/bin/env bash兼容 NixOS / 最小 Alpine后的第二行part 2陈旧检测器 hooks/gsd-check-update-worker.js 的版本正则必须同时匹配 Bash 的#与 JS 的//两种注释风格对应原问题 #2136/#2206——早期正则只匹配//导致 Bash hook 永远落入 unknown 分支part 3a / 3binstall.js的 bundled 路径与 Codex 路径都必须对.sh做{{GSD_VERSION}}替换不得用copyFileSync直拷跳过模板展开part 4端到端跑真实安装器后断言已安装.sh含具体 semver 版本、不含字面量{{GSD_VERSION}}并用与生产一致的检测正则跑一遍陈旧检测断言全新安装后 stale bash hooks 为零。part 4 之所以此前会偶发失败正是因为并行安装测试从被截断的hooks/dist/里拿到了空源文件——它既充当了 bug 的引爆点也天然成为修复后的守门人。原子写入落地后空文件窗口消失part 4 的端到端断言在任何并发度下都稳定通过。工程启示一份值得沉淀的并发写入方法论从这次修复中可以提炼出对任何多进程写共享产物目录场景都可复用的四条原则读者永远不接触半成品不要在目标路径上做就地覆盖先写暂存、后原子换名文件系统层面对写入目标就位的时序语义要与读写双方同时约定。暂存区必须与目标同文件系统rename(2)的原子性只在同一文件系统内成立跨设备会退化为非原子的拷贝同时暂存区应放在目标的同级兄弟位置避免基于目录枚举的读者看到临时条目。进程隔离是比锁更廉价的并发策略以process.pid命名暂存目录天然消灭多写者争抢同一中间资源的问题也免去了复杂的加锁与超时管理。跨平台语义差异要显式兜底Windows 不具备 POSIX rename 的原子替换语义需要配合短退避重试 → 降级拷贝 → 保留旧产物的三级策略并接受最坏情况下对单文件的非原子妥协见 scripts/build-hooks.js 的renameAtomicWithRetry注释与实现。对排查同类仅个别 CI 节点失败问题的团队而言本案例还提供了一个诊断范式当同一 SHA 表现漂移时优先审查构建产物被多个消费者并发读写的路径——测试驱动器scripts/run-tests.cjs的默认并发度--test-concurrency4、测试before()钩子对构建脚本的重复调用共同把一次本可无感的写入放大成了发布阻断。理解了这些触发条件就理解了为什么修复落点在构建脚本而非测试编排把产物写入变为原子操作后无论多少个消费者并发读取观察到的始终是完整文件。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考