VS Code调试Go需满足：go≥1.16、GO111MODULE=on、存在go.mod；仅装官方Go扩展，禁用旧插件；gopls自动管理，调试须确保package main且配置正确launch.json；GOPROXY等网络设置影响依赖拉取。
VS Code 本身不内置 Go 支持，必须靠 go 命令行工具 + gopls + VS Code 扩展协同工作；直接设 GOPATH 已是过时做法，Go 1.16+ 默认启用模块模式（GO111MODULE=on），强行配置旧式 GOPATH 反而会干扰依赖解析和调试。
确认 go 环境和模块模式是否就绪
在终端运行以下命令，结果必须全部符合要求，否则后续所有配置都会出问题：
-
go version输出 ≥go1.16 -
go env GOPATH可以有输出，但你**不需要手动修改它**；模块项目根本不用依赖这个路径 -
go env GO111MODULE必须返回on（Go 1.16+ 默认值）；若为auto或off，需执行go env -w GO111MODULE=on - 项目根目录下存在
go.mod文件（用go mod init example.com/foo初始化）
安装正确扩展并禁用过时插件
VS Code 插件市场里搜 “Go”，只装官方维护的 Go by Go Team at Google（ID：golang.go），其他如 “Go Extension Pack”、“Go Nightly” 等全部卸载。该扩展会自动下载并管理 gopls（Go Language Server），它是调试、跳转、补全的核心。
关键设置项（在 VS Code 设置 JSON 中）：
立即学习“go语言免费学习笔记（深入）”；
"go.toolsManagement.autoUpdate": true, "go.gopath": "", // 留空，不要填任何路径 "go.useLanguageServer": true,
如果之前手动装过 dlv（Delve），确保它是通过 go install github.com/go-delve/delve/cmd/dlv@latest 安装的，而非旧版 github.com/derekparker/delve —— 后者不支持 Go 模块调试。
调试前必须验证 main 包结构和 launch.json 配置
Delve 调试器只认标准 main 包入口。常见失败原因不是配置错，而是代码本身不满足调试前提：
- 当前打开的文件必须属于一个
package main，且包含func main() - 不能在
internal/或cmd/subcmd/这类子目录下直接按 F5 启动 —— VS Code 默认只找项目根目录的main.go - 若要调试子命令（如
cmd/api/main.go），需显式配置launch.json：
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug api",
"type": "go",
"request": "launch",
"mode": "test", // 或 "exec"
"program": "${workspaceFolder}/cmd/api/main.go",
"env": {},
"args": []
}
]
}
mode: "exec" 适用于可执行文件，mode: "test" 更稳妥，能绕过部分模块路径解析问题。
GOPATH 不用设，但 GOPROXY 和 GOSUMDB 得留意
国内用户最常卡在依赖拉取失败，这不是 VS Code 的锅，而是 Go 工具链的网络问题：
- 执行
go env -w GOPROXY=https://proxy.golang.org,direct→ 替换为国内镜像，例如：https://goproxy.cn - 若用私有模块或公司内网仓库，还需设
go env -w GOPRIVATE=git.example.com/* -
GOSUMDB=off仅用于离线开发或内部模块，生产环境慎用；否则go get会因校验失败中断
这些环境变量改完后，务必重启 VS Code 终端（或整个窗口），因为 gopls 启动时会缓存初始环境。
真正容易被忽略的是：VS Code 的 Go 扩展会在后台静默启动 gopls，而它的日志默认不显示。一旦补全失效或断点不命中，第一反应不该是重装插件，而是打开命令面板（Ctrl+Shift+P），运行 Go: Toggle Verbose Logging，再看输出通道里的 gopls 错误——多数时候是 go.mod 里某条 replace 指向了不存在的本地路径，或者 go.work 文件干扰了单模块识别。
