VSCode调试Go程序需满足dlv≥1.21且路径正确、gopls正常、项目含go.mod三前提；launch.json中program与mode须匹配目标类型；断点不命中多因源码路径与模块路径不一致。
VSCode 调试 Go 程序的核心前提是 dlv 可用且版本 ≥ 1.21，gopls 正常运行，项目有 go.mod —— 缺一不可。不是装了插件就能调，很多“断点不命中”“调试启动失败”问题都卡在这三处。
dlv 版本和安装路径必须被 VSCode 正确识别
VSCode Go 扩展不会自己猜 dlv 在哪，它依赖系统 PATH 或显式配置。即使你用 go install github.com/go-delve/delve/cmd/dlv@latest 装好了，也可能因为 GOPATH/bin 或 GOBIN 没进 PATH 导致 VSCode 找不到。
- 终端执行
dlv version，确认输出类似Delve Debugger<br>Version: 1.23.0
（2026 年推荐 ≥ 1.22） - 如果报 command not found，检查
go env GOPATH和go env GOBIN，把对应bin目录加进系统 PATH - 不要手动改
launch.json里的dlvPath字段——VSCode Go 插件已弃用该字段，它只认环境变量或 PATH 中的dlv - 多 Go 版本管理用户（如
gvm或asdf）需确保当前 shell 的 Go 版本与dlv编译时一致，否则可能报incompatible dlv binary
launch.json 的 program 和 mode 必须匹配实际目标类型
program 不是“随便填个路径就行”，它决定 dlv 启动时编译什么、怎么加载符号；mode 则告诉调试器你是跑 main、测函数，还是 attach 进程。
- 调试主程序：用
"mode": "auto"+"program": "${workspaceFolder}"（要求根目录含main.go且go.mod存在） - 调试单个测试函数：
"mode": "test"+"program": "${workspaceFolder}"+"args": ["-test.run", "TestFoo"] - 调试子命令（如
cmd/api/main.go）："program": "${workspaceFolder}/cmd/api"，不能写成main.go文件路径（dlv debug不接受 .go 后缀文件） - 远程调试必须用
"mode": "remote"，且服务端要先运行dlv dap --headless --listen :2345 --api-version 2
断点不命中？先看源码路径和模块路径是否对齐
VSCode 显示红点 ≠ 断点真生效。常见原因是 dlv 加载的二进制符号路径与你在编辑器里打开的文件路径不一致——尤其发生在多模块、replace、go.work 场景下。
- 打开调试控制台（Run → Open Debug Console），看是否有类似
could not find file /home/xxx/go/src/.../main.go的警告 - 检查
go list -f '{{.Dir}}' .输出是否与program字段指向的路径一致 - 若用了
replace指向本地路径，确保该路径是绝对路径，且没有软链接嵌套（dlv对 symlink 解析不稳定） - 在
main函数第一行设断点，如果这里都跳过，基本可判定是模块路径错配或go build阶段没读到正确go.mod
调试 Web 服务时，端口冲突和热重载会干扰调试流
Go Web 服务（如 Gin、Echo）常监听 :8080，但 VSCode 默认调试不杀进程，第二次 F5 会因端口占用直接 panic，这不是配置问题，是调试模式本身限制。
- 避免在
launch.json里硬编码端口，改用env注入："env": { "PORT": "0" }让 OS 分配空闲端口 - 禁用开发服务器的热重载（如 Gin 的
gin run），改用go run或dlv debug直接启动，否则调试器无法接管进程生命周期 - 想边改边调？用
dlv exec ./your-binary模式，但需先go build，且./your-binary必须带 DWARF 符号（默认开启，除非加了-ldflags="-s -w"）
真正卡住调试的，往往不是 launch.json 写错，而是 dlv 启动时看到的模块路径和你在编辑器里看到的不是同一个世界。每次调试前，花 10 秒跑一遍 go list -m 和 dlv version，比反复重启 VSCode 有效得多。
