手已经搭在笔记本屏幕边上,准备合盖了。
那是九月末一个晚上,十一点多。终端里的同步脚本刚跑完最后一步,GitHub Actions 页面整整齐齐亮起一排绿色对勾:上游最新代码拉下来了,本地保留的兼容测试过了,生产构建没报错,自动生成的合并提交也顺顺当当推回了主分支。我心想,今天这桩差事算是了了。
合盖之前,鬼使神差地,我又刷新了一下仓库主页。
提交记录旁边,Vercel 的状态图标顶着一个刺眼的红叉。它拒绝发布这次提交,线上跑着的还是旧版本。
那排绿勾只管它眼皮底下的事
说起来,这次同步跑通之前,流水线刚在另一个不起眼的角落里栽过跟头。脚本在生成工作树提交的瞬间,上游仓库顺带装进来的 lint-staged 钩子突然插手,试图在后台自动执行一次 stash 操作;可镜像工作区里根本没有适合它暂存的中间状态,整个流程就硬生生地卡死在 Commit and push 那一步。
修起来倒不费事:让同步脚本生成提交时绕开仓库作者预设的客户端钩子,应用层的检查和测试照旧留在前面的步骤里。(当时改完看着流水线重新跑通,我还得意地灌了一大口冰水,以为万事大吉了。)
补丁打上后,编号为 36310785008 的那次 Run 从拉取上游开始一路绿到底。它确实扎扎实实干完了一长串活:对应上游提交 bb6ac766e555,依赖在容器里装好,fork 分支里保留的兼容性测试全部过关,生产构建正常打包,生成的提交稳稳落进 main 分支。
可这一排绿勾能交代的,也就到此为止了。它既管不着远在另一端托管平台上的 Vercel 能不能用同一棵代码树跑完部署,更管不着读者打开的博客首页、文章页和 RSS 订阅源有没有真换成刚打出来的这包新代码。盯着屏幕发了会儿呆,我才慢慢回过味来:平时我们太习惯把流水线上的绿色当成一张包揽全局的合格证了,仿佛只要亮起绿灯,剩下的事情就会顺理成章地发生。可实际上,依赖装上、测试通过、产物打出来、代码推上远端、托管平台接住产物,这几件事在时间线上固然挨着先后次序,却没有任何一个环节能替后面的路程打包票。
失败停在复制设计系统的地方
揉了揉发酸的眼睛,我没急着去点重跑同步,先顺手点开了 Vercel 后台的部署日志。好在它没藏着掖着,把项目根目录、触发提交以及报错退出的那行命令交代得清清楚楚:Vercel 里的项目根目录设在 apps/web,自定义安装命令会先退回工作区根目录,执行一句 git submodule update,随后再把 design-oss/design-system 下的文件复制到 packages/design-system。
病根恰恰就出在这个子模块上。Vercel 的构建容器拉完代码,原地只留下一个空荡荡的子模块外壳,压根没把设计系统仓库的真实内容拉下来。后面的复制命令一跑,连源目录的影子都摸不着,整个构建流程还没跨进 Next.js 的大门就草草结束了。
更有迷惑性的是,这时候拿浏览器去访问线上的两个旧页面,服务端照样气定神闲地回 200,界面排版也看不出半点破绽。要不是睡前多瞄了一眼后台,我根本不会知道最新那次提交被挡在了生产环境的大门外。
这种静默的失败在日常维护里最容易让人掉以轻心。业务代码一行没写错,后端的 API 接口也照常响应,只是构建容器里的环境假设和代码仓库里的子模块没对上,新版本就这么悄无声息地停在了半路上。
第一次修复还不够
弄清空目录的来龙去脉后,我把 Vercel 项目后台的安装命令改写成了一套带兜底的显式流程:先检查 design-oss/design-system 里有没有东西,目录不存在或者为空,就直接当场浅克隆一份公开的 Yohaku 仓库下来;等把设计系统源码实实在在复制到目标位置后,再去执行工作区的依赖安装。
满以为这下药到病除了。重新触发部署,子模块找不到的报错确实销声匿迹了,构建日志紧接着又抛出了第二个拦路虎。
这回翻脸的是包管理器:工作区根目录的 pnpm-lock.yaml 里,找不到 packages/design-system 这个 importer。仔细想想也合情合理,设计系统本来是以独立子模块的身份挂进来的,主仓库的锁文件从没为它预留过依赖入口;现在我们在构建机上硬把源码复制成了工作区里的一个子包,Vercel 默认开启的严格冻结安装(frozen lockfile)立刻亮起红灯,锁文件和实际目录结构对不上,它一步也不肯往下走。
第二个报错比第一个更有嚼头。它逼着我正面撞上了打补丁的隐性代价:在构建环境里临时拼凑出一个运行时的源码目录,就必须坦然面对现有锁文件从没描述过它这件事。权衡之下,我把兜底方案改成 pnpm install --no-frozen-lockfile,让构建机根据工作区里的真实目录现场补全依赖关系。
说实话,从软件供应链严谨性的角度看,这绝不算什么值得夸耀的长期方案,可重复性比严格的锁文件冻结模式打了折扣。但它的好处是把缺失的前置条件明明白白写进了命令里,不再一厢情愿地指望托管平台在暗地里替我把子模块打理好。哪天上游把设计系统正式纳入可冻结的工作区结构,这行权宜之计也就可以功成身退了。
带着这行改动的第二次部署,总算一路走到了底。我盯着 Vercel 的实时控制台,看依赖安装、Next.js 编译打包、产物上传一步步跑完,km.caiths.com 终于被顺利指向了新的生产环境别名。紧接着又在终端里分别请求了两个自定义域名,都拿到 200 响应,响应体字节数和 ETag 校验值也全都换成了新的指纹。即便这样,我还是老老实实打开浏览器,把几个核心页面挨个巡检了一遍,确认排版和交互都没事,肩膀才真正松下来。
速度快了,阅读不能省掉
关掉密密麻麻的构建日志,窗外已经过了零点。我靠在椅背上,想起前阵子在笔记里写过的一段感触。那时候刚从简单的网页对话框换到 Coding Agent,代码生成、命令执行、测试跑通全在一瞬间提了速,坐在屏幕前的我却常有一种快要跟不上趟的恍惚。起初我以为那只是换了工具的陌生感,冲淡了一点亲手敲代码的乐趣;今晚在那个红叉面前来回折腾了一通,我才看清了这种“快”背后的另一面。
倘若我只满足于盯着 GitHub Actions 那排绿勾,今晚的活在脚本跑通那一刻就草草收场了;倘若我只拿“网页能打开、域名回 200”当标尺,我也同样会在旧缓存的掩护下心安理得去睡觉。真正决定系统通没通的功夫,恰恰夹在这两个看似风平浪静的切片中间:耐着性子翻枯燥的报错日志,核对容器里的目录结构,坦然承认第一刀修复顺带切开了第二个缺口,再去掂量放宽锁文件限制究竟要背多少技术债。
这几步摸排非但没有让手头的活变快,反倒让我在一条已经显示“通过”的流水线跟前站了很久。自动化带来的高速度,原本只该用来压缩那些机械的动作,人脑的阅读和判断却省不得。跨系统部署这种环节繁多的链条尤其如此:源码仓库、CI 容器、托管构建平台、边缘缓存、域名解析,各自都只管眼皮底下那一小段,没有任何一处的绿灯有资格替终点打包票。
经过这一遭,我在运维笔记里把“部署完成”这个轻巧的词划掉了,换成一组必须亲眼确认的核对项:同步任务记下的上游 SHA 和生成的提交哈希,Vercel 走到底的构建日志,重新绑定的生产别名,两个自定义域名实打实的响应头变化,再加上亲手点开的几个核心页面。
这一晚我没写新文章,后端数据结构也一行没动,只是疏通了一条自动同步的暗渠。合上电脑的时候想,工具替我们把路走得越快,坐在屏幕前的人,反而更得给自己留出一点耐性,把沿途的结果一行一行读完。