调试阶段必须禁用 replace 本地路径，因其绕过模块校验，导致 gopls 和 dlv 无法解析真实导入路径、断点失效；应使用 go mod edit -dropreplace 或分支隔离替代，且 vs code 必须打开模块根目录。
调试阶段的 Go 环境必须禁用 replace 本地路径
本地 replace（如 replace github.com/foo/bar => ./bar）在调试时极易导致模块加载不一致、断点失效、dlv 无法解析源码路径。这不是配置问题，而是 Go 工具链对 replace 的语义限制：它绕过模块校验，使 gopls 和 dlv 看不到真实导入路径。
- 调试前务必执行
go mod edit -dropreplace=github.com/foo/bar（或删掉go.mod中对应行） - 若需临时修改依赖，用
go mod edit -replace+git checkout -b debug-branch分支隔离，而非本地路径 replace -
dlv debug启动时若报could not find source for ...，第一反应不是路径错，而是检查是否残留 replace
增量编译靠的是 go build -a 缓存 + fsnotify 轻量监听
Go 本身没有“热重载”，但调试阶段追求的是“改完保存 → 1 秒内重启服务”。靠的是两层机制：底层用 go build -a 强制重建所有依赖（避免 stale object），上层用 fsnotify 监控文件变化触发重建 —— 不是靠 IDE 插件，也不是 air 这类封装过重的工具。
- 写个最小
Makefile：watch: fsnotify -r -e write . -c 'make build && ./server'
-
build目标必须含go build -a -o ./server ./cmd/server，-a是关键，否则修改internal/包后可能跳过重编 - 避免用
go run main.go做增量调试：它每次清空临时构建目录，无法复用缓存，实测比go build -a慢 2–3 倍
gopls 和 dlv 的调试路径必须与 GOPATH/GOROOT 完全解耦
现代 Go 调试不依赖 GOPATH，但 gopls 和 dlv 对工作区路径敏感。常见断点不命中，90% 是因为 VS Code 打开的是子目录（如 ./cmd/api），而非模块根目录（含 go.mod 的顶层目录）。
- VS Code 必须用「File → Open Folder」打开整个模块根目录，不能只开
cmd/或internal/子目录 -
dlv dap启动时若报no debug info for …，先运行go list -m确认当前目录是模块根，再检查go env GOROOT是否指向真实安装路径（不是 symlink） -
gopls日志里出现no metadata for …，大概率是打开了错误目录，或go.mod文件被 IDE 自动删了注释行（某些插件会格式化go.mod导致损坏）
调试时的 pprof 必须在进程启动后立即注册，而非等 HTTP handler
很多教程教你在 http.HandleFunc("/debug/pprof/", pprof.Index)，但这对调试无效：dlv attach 时 profile 接口还没注册，抓不到启动初期的 CPU/heap 样本。
- 把
pprof.StartCPUProfile和pprof.WriteHeapProfile放到main()开头，早于任何 goroutine 启动 - 调试中想 dump 当前 heap，直接发
SIGQUIT：kill -QUIT $(pidof server)，会在 stdout 输出 stack + heap summary - 不要依赖
net/http/pprof的 Web 接口做调试分析 —— 它需要请求触发，而你正在单步调试，根本没机会发 curl
dlv 的 --headless 模式下，goroutine 列表和 stacktrace 默认不展开；必须手动输入 goroutines 再 goroutine <id> bt</id>，没人提醒你这一步，但卡住时往往就差这一条命令。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
