必须安装匹配版本的dlv调试器并配置正确launch.json：mode需设为auto/exec/test，program用相对路径，envFile路径相对于workspaceFolder；断点失效需检查go.mod和GOPATH冲突；Web调试应避免端口冲突并禁用air双启动。
Go调试前必须装对的扩展和工具
VSCode 调试 Go 程序不是装个插件就完事，dlv（Delve）调试器必须手动安装且版本要匹配。VSCode 的 Go 扩展（由 Go Team 维护）会提示你安装，但它默认调用的是 dlv 命令——如果系统 PATH 里没有，或者版本太老（比如 v1.20 以下），就会卡在 “Starting dlv” 或报错 could not launch process: fork/exec /usr/bin/dlv: no such file or directory。
- 运行
go install github.com/go-delve/delve/cmd/dlv@latest安装最新稳定版（注意：不是go get） - 检查是否生效：
dlv version应输出 v1.21+（Go 1.21+ 推荐用 v1.22+） - 如果用的是 Go Workspace 模式（
go.work），确保dlv在 workspace 根目录下可执行，否则断点可能不命中
launch.json 配置里最关键的三个字段
VSCode 的调试依赖 .vscode/launch.json，但很多用户直接复制网上配置，结果无法 attach、无法读取环境变量、或调试时找不到 main 包。真正起作用的只有几个字段：
-
mode必须明确：调试单文件用"mode": "test"；调试整个 module 用"mode": "exec"（需先go build）；最常用的是"mode": "auto"（自动识别，但要求当前是 main package 且有main.go） -
program是相对路径，不是包名：写"program": "./cmd/myapp"，不是"program": "myapp"；如果项目没分 cmd 目录，就写"program": "." -
env和envFile二选一即可：envFile更安全，支持.env文件加载，但路径是相对于workspaceFolder，不是launch.json所在位置
断点不触发？检查 GOPATH 和 module 初始化状态
断点灰色、hover 显示 “unbound breakpoint”，大概率不是配置问题，而是 Go 的构建上下文没对上：
- 如果项目还没运行过
go mod init，VSCode 会 fallback 到 GOPATH 模式，此时dlv可能按 GOPATH 路径找源码，但你的文件实际在别处 -
go env GOPATH输出的路径下不能存在同名包，否则dlv会优先加载 GOPATH 里的旧版本 - 检查当前目录是否有
go.mod：没有就先go mod init example.com/myapp，再删掉~/.go/pkg/mod/cache（有时缓存导致符号表错乱）
调试 Web 服务时端口被占或热重载失效
用 gin 或 air 开发 Web 服务时，直接 debug main.go 会导致两个进程争抢 8080 端口，或者修改代码后调试会中断：
立即学习“go语言免费学习笔记（深入）”；
- 不要用
air+ VSCode debug 双启动；改用dlv exec ./myapp -- --port=8081（把端口挪开） - 如果必须热重载调试，推荐在
launch.json中加"args": ["--port=8081"]并禁用air的 auto-build，改用 VSCode 的 “Run Task” 触发go build后再调试 -
dlv默认不支持 fork 子进程调试（比如exec.Command启的服务），需要加参数--follow-fork，但仅限 Linux/macOS，Windows 不支持
Go 调试真正卡住的地方，往往不在 VSCode 界面操作，而在 dlv 和 Go 构建模式之间的隐式契约——它不报错，只沉默跳过断点。多看 DEBUG CONSOLE 里 dlv 启动时的输出路径，比反复点“开始调试”有用得多。
