跳转至

worktree 的 node_modules 软链被提交,合并回主树后毁掉全部依赖

症状

合并派活 worktree 的分支后,主树任何 pnpm 命令立刻失败:

ELOOP: too many symbolic links encountered,
realpath '/Users/tony/Work/01_Data/02_laifaxin-chajian-ditu/node_modules'

ls -ld node_modules 显示它变成了指向自己的软链,真实依赖目录已被覆盖。

根因链(四步,每步单独看都无害)

  1. 主控给派活 worktree 建依赖软链: ln -s <主树>/node_modules <worktree>/node_modules —— 让执行方能跑 tsc / vitest
  2. .gitignore 第 8 行写的是 node_modules/(带尾斜杠)。 🔴 尾斜杠在 gitignore 里只匹配目录,不匹配软链 —— 软链在 git 眼里是文件 ⇒ 该软链没有被忽略,git status 显示为 ?? node_modules
  3. 执行方按任务书跑 git add -A 提交交付 ⇒ 软链条目进了 commit
  4. 主控 git merge 回主树 ⇒ git 在主树按索引创建同名软链, 覆盖真实的 node_modules 目录 ⇒ 软链指向的正是主树自己 ⇒ 自引用循环

为什么没被更早发现

  • 第 2 步的现象(?? node_modules)在第一轮派活时确实暴露过: 执行方 sol-dsh 把它当作「工作区不干净」判 NO-GO 并停止 —— 那次它救了一命。
  • 主控当时的处置是「在任务书里说明这条是预期的,不算前提不符」 —— 治了症状(让执行方别停),没治根因(让 git 真正忽略它)。
  • 第二轮执行方照做,git add -A 就把它带进去了。

⇒ 教训:当一个「预期的噪音」需要你在文档里反复解释时,它就该被机制消除,不是被解释。

修复

.gitignore 的 node_modules/ 改为 node_modules(去掉尾斜杠), 同时匹配目录与软链。

恢复方法(如果已经发生)

rm node_modules                       # 删掉自指软链(它不指向任何真实内容,安全)
pnpm install --frozen-lockfile        # 从 lockfile + 本地 store 确定性恢复
本次实测 14.2 秒完成(pnpm store 本地已有 1.9G 缓存,无需下载)。

回归判据

grep -c '^node_modules$'  .gitignore   # 期望 1(无尾斜杠)
grep -c '^node_modules/$' .gitignore   # 期望 0
# 在任一带软链的 worktree 里:
git status --porcelain node_modules    # 期望空

同类前科

0092-gitignore-icon-pattern-breaks-clone-build —— 裸 Icon 规则误伤 src/public/icon/ 整个目录。两次都是 gitignore 的匹配语义与直觉不符: 一次是「太宽」(Icon 匹配到目录名),一次是「太窄」(node_modules/ 漏掉软链)。

⇒ 改 gitignore 必须逐条实测匹配结果,不能靠读。