根本原因追踪概述Bug 常常在调用栈深处显现在错误的目录中执行 git init、在错误的位置创建文件、用错误的路径打开数据库。您的本能是在错误出现的地方修复但那只是在处理症状。核心原则沿调用链向后追踪直到找到原始触发点然后在源头修复。何时使用digraph when_to_use { Bug appears deep in stack? [shapediamond]; Can trace backwards? [shapediamond]; Fix at symptom point [shapebox]; Trace to original trigger [shapebox]; BETTER: Also add defense-in-depth [shapebox]; Bug appears deep in stack? - Can trace backwards? [labelyes]; Can trace backwards? - Trace to original trigger [labelyes]; Can trace backwards? - Fix at symptom point [labelno - dead end]; Trace to original trigger - BETTER: Also add defense-in-depth; }使用场景错误发生在执行深处不是在入口点堆栈跟踪显示很长的调用链不清楚无效数据从哪里产生需要找出哪个测试/代码触发了问题追踪流程1. 观察症状Error: git init failed in /Users/jesse/project/packages/core2. 找到直接原因哪段代码直接导致了这个错误awaitexecFileAsync(git,[init],{cwd:projectDir});3. 追问是谁调用了这里WorktreeManager.createSessionWorktree(projectDir,sessionId)→ 由 Session.initializeWorkspace()调用 → 由 Session.create()调用 → 由测试中的 Project.create()调用4. 继续向上追踪传入了什么值projectDir 空字符串空字符串作为cwd会解析为process.cwd()那就是源码目录5. 找到原始触发点空字符串从哪里来constcontextsetupCoreTest();// 返回 { tempDir: }Project.create(name,context.tempDir);// 在 beforeEach 之前被访问添加堆栈跟踪当您无法手动追踪时添加插桩// 在有问题的操作之前asyncfunctiongitInit(directory:string){conststacknewError().stack;console.error(DEBUG git init:,{directory,cwd:process.cwd(),nodeEnv:process.env.NODE_ENV,stack,});awaitexecFileAsync(git,[init],{cwd:directory});}关键点在测试中使用console.error()而不是 logger——可能不会显示运行并捕获npmtest21|grepDEBUG git init分析堆栈跟踪查找测试文件名找到触发调用的行号识别模式同一个测试同一个参数找出哪个测试造成了污染如果在测试过程中出现了某些东西但您不知道是哪个测试使用本目录中的二分脚本find-polluter.sh./find-polluter.sh.gitsrc/**/*.test.ts逐个运行测试在第一个污染者处停止。用法请参阅脚本。真实案例空的 projectDir症状.git被创建在packages/core/源码中追踪链git init在process.cwd()中执行 ← 空的 cwd 参数WorktreeManager 被用空的 projectDir 调用Session.create() 传入了空字符串测试在 beforeEach 之前访问了context.tempDirsetupCoreTest() 初始返回{ tempDir: }根本原因顶层变量初始化时访问了空值修复将 tempDir 改为 getter如果在 beforeEach 之前被访问就抛出异常同时添加了纵深防御第 1 层Project.create() 验证目录第 2 层WorkspaceManager 验证非空第 3 层NODE_ENV 守卫拒绝在 tmpdir 之外执行 git init第 4 层执行 git init 前记录堆栈跟踪关键原则digraph principle { Found immediate cause [shapeellipse]; Can trace one level up? [shapediamond]; Trace backwards [shapebox]; Is this the source? [shapediamond]; Fix at source [shapebox]; Add validation at each layer [shapebox]; Bug impossible [shapedoublecircle]; NEVER fix just the symptom [shapeoctagon, stylefilled, fillcolorred, fontcolorwhite]; Found immediate cause - Can trace one level up?; Can trace one level up? - Trace backwards [labelyes]; Can trace one level up? - NEVER fix just the symptom [labelno]; Trace backwards - Is this the source?; Is this the source? - Trace backwards [labelno - keeps going]; Is this the source? - Fix at source [labelyes]; Fix at source - Add validation at each layer; Add validation at each layer - Bug impossible; }永远不要只在错误出现的地方修复。回溯以找到原始触发点。堆栈跟踪技巧在测试中使用console.error()而不是 logger——logger 可能被抑制在操作之前在危险操作之前记录而不是在它失败之后包含上下文目录、cwd、环境变量、时间戳捕获堆栈new Error().stack显示完整的调用链实际影响来自调试会话2025-10-03通过 5 层追踪找到了根本原因在源头修复getter 验证添加了 4 层防御1847 个测试通过零污染
