Go 程序在 VS Code 中调试（Debug）指南
1. 环境准备（一次性）
| 步骤 | 命令 / 操作 |
|---|
| 安装 Go | https://go.dev/dl/（推荐 1.23+）go version 能输出版本即可 |
| 配置 GOPATH / Go modules | 推荐使用 module 模式（go mod init xxx），不需要手动设 GOPATH |
| 安装 Delve（dlv） | VS Code 内部会自动下载，但手动确认：<br>go install github.com/go-delve/delve/cmd/dlv@latest |
| 环境变量 | GOROOT、GOPATH、PATH 包含 $GOROOT/bin 与 $GOPATH/bin（大多数系统已自动） |
快速安装依赖：
- 安装 Go 语言扩展（
golang.go）
- 快捷键
Ctrl + Shift + P 调出面板，选择“Go: Install/Update Tools”
- 全选扩展，点击“OK”保存。
2. VS Code 必装插件
- Go（官方） – 提供代码补全、格式化、测试、调试
- （可选）CodeLLDB – 如果想用原生 LLDB 调试（不推荐，Delve 更强）
安装后 重启 VS Code，打开任意 .go 文件会提示安装额外工具，全部点 Install All。
3. 项目结构 & launch.json
3.1 简单项目示例
myapp/
├─ go.mod
├─ main.go
└─ .vscode/
└─ launch.json <-- 自动生成或手动创建
main.go（示例）：
package main
import (
"fmt"
"time"
)
func main() {
for i := 0; i < 5; i++ {
fmt.Println("count:", i)
time.Sleep(500 * time.Millisecond)
}
}
3.2 让 VS Code 自动生成 launch.json
- 打开 Run → Add Configuration…
- 选择 Go: Launch package（默认就是 Delve）
- VS Code 会在
.vscode/launch.json 中写入类似：
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch Package",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}"
}
]
}
3.3 常用配置项（按需改）
| 字段 | 说明 | 示例 |
|---|
program | 要调试的包路径 | "${workspaceFolder}/cmd/myapp" |
args | 命令行参数 | ["-config", "dev.yaml"] |
env | 环境变量 | { "ENV": "dev" } |
buildFlags | 编译参数 | "-tags=integration" |
dlvFlags | 直接传给 dlv | ["--log"] |
mode | auto / debug / test / exec | debug 强制编译调试符号 |
port | 自定义 dlv 端口（多实例时） | 40001 |
完整示例（带参数、环境变量）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug MyApp",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}",
"env": {
"ENV": "local"
},
"args": ["-port", "8080"]
}
]
}
4. 调试实战步骤
- 打开要调试的文件（如
main.go）
- 在左侧行号点击 设置 断点（红点）
- 按 F5（或 Run → Start Debugging）
- 程序会在断点处暂停，左侧出现 变量、监视、调用栈、断点 面板
常用操作快捷键
| 快捷键 | 功能 |
|---|
| F5 | 继续运行 |
| F10 | 步过（Step Over） |
| F11 | 步入（Step Into） |
| Shift+F11 | 步出（Step Out） |
| Ctrl+Shift+F5 | 重启调试 |
| F9 | 切换断点 |
高级技巧
| 场景 | 操作 |
|---|
| 条件断点 | 右键断点 → Edit Breakpoint → i == 3 |
| 表达式求值 | 在 Debug Console 输入 p fmt.Sprintf("%#v", obj) |
| 监视变量 | 右键变量 → Add to Watch |
| 修改变量值 | 在 Variables 面板右键 → Set Value |
| 远程调试 | dlv debug --headless --listen=:2345 --api-version=2 → launch.json 加 "port": 2345, "mode":"remote" |
5. 常见问题 & 排查
| 症状 | 可能原因 | 解决办法 |
|---|
| “Could not launch process: decodestub” | 没装 dlv 或 Go 版本太老 | go install github.com/go-delve/delve/cmd/dlv@latest |
| 断点灰色（未绑定） | 源码与二进制不匹配（Release 编译） | 确保 mode: "debug" 或加 buildFlags: "-gcflags='all=-N -l'" 禁用优化 |
| 调试时程序直接退出 | main 里没有阻塞（如 http.ListenAndServe） | 加 select{} 或 <-ch 让程序挂住 |
| 多模块项目找不到包 | program 指向错误 | 用 ${workspaceFolder}/cmd/xxx 指向具体二进制目录 |
| Windows 报 “Access is denied.” | 防病毒软件拦截 dlv.exe | 把 dlv.exe 加入白名单或临时关闭杀毒 |
6. 一键复制的完整 launch.json（推荐保存）
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Current Package",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}",
"env": {},
"args": [],
"showLog": true,
"buildFlags": "-gcflags='all=-N -l'"
}
]
}
把 -gcflags='all=-N -l' 加上后，禁用内联和优化，断点永远能命中。
完毕！
现在你只需要：
- 装好 Go + VS Code + Go 插件
- 把上面的
launch.json 放进 .vscode/
- 打断点 → F5 → 愉快调试
