Go 程序出现 bug、崩溃、死锁、竞态或异常行为时…

当 Go 代码出现编译失败、逻辑错误、随机崩溃、偶发失败、卡死、CPU/内存异常或延迟飙升时，按证据驱动流程排查根因。

适用场景

解决思路

1. 先读错误信息：定位文件与行号；类型不匹配检查函数签名与接口实现；undefined 检查导入、导出名与 build tag；cannot use X as Y 检查具体类型与接口。
2. 修复前先复现：写一个能捕获该 bug 的失败测试，使其确定性复现，隔离最小失败示例，必要时用 git bisect 找到引入问题的提交。
3. 不要靠直觉：性能与并发问题用 pprof、race detector、benchmark 测量，而不是猜测。
4. 一次只验证一个假设：每次只改一处，测量并确认，避免同时改多处导致无法归因。
5. 必须找到根因再修复：从症状反向追踪数据流，质疑自己的假设，连续追问五次为什么，直到定位真正根因；不要用掩盖症状的临时补丁。
6. 研究整个代码库而非只看 diff：追踪调用方传入的值，检查上游校验、类型转换、guard 子句，阅读中间件、拦截器、init 函数等上下文；若上下文降低严重性但未消除问题，仍按较低优先级报告并加注释说明上游保证。
7. 从简单工具开始：本地调试可先用 fmt.Println，逐步升级到日志、pprof、Delve；生产环境禁止用 fmt.Println，改用 slog。
8. 按决策树分流症状：编译失败用 go build ./... 2>&1 与 go vet ./...；逻辑错误写失败测试并检查错误处理、nil、边界；随机崩溃用 GOTRACEBACK=all ./app 与 go test -race ./...；偶发失败用 go test -race ./...；卡死用 curl localhost:6060/debug/pprof/goroutine?debug=2；高 CPU 用 pprof CPU profiling；内存增长用 pprof heap profiling；延迟高用 CPU + mutex + block profiles。
9. 警惕调试红旗：出现“先快速修一下以后再查”、同时做多处修改、不理解原因就提修复、每个修复引出新问题、同一问题尝试 3 次以上、只在我机器上能跑、甩锅框架/标准库/编译器时，停止并回到第一步。
10. 单问题调试保持串行：按 Golden Rules 顺序读错误、复现、一次一个假设，不要启动子代理。
11. 大规模代码库 bug 扫描时，按五类 bug 启动最多 5 个并行子代理：nil/接口、资源、错误处理、竞态、context/slice/map。
12. 使用 Delve 前先安装：go install github.com/go-delve/delve/cmd/dlv@latest。
13. 参考对应文档深入：通用方法论、常见 Go bug、测试驱动调试、并发调试、性能排查、pprof、诊断工具、生产调试、编译问题、代码审查红旗。

适用边界 · 注意事项

• 仅需解读 profile 或做基准测试时（应使用 golang-benchmark 技能）
• 仅需应用优化模式时（应使用 golang-performance 技能）
• 设计新代码时（防御性编码用 golang-safety，并发设计用 golang-concurrency）