VSCode 无法运行 Go 程序的根本原因是环境变量未正确继承，导致内置终端找不到 go 命令或 gopls 初始化失败；需确保从终端启动 VSCode、go 在 PATH 中、项目根目录含 go.mod、launch.json 的 program 指向具体 .go 文件，并配置 GOPROXY 和 GOBIN。
VSCode 本身不运行 Go 程序，它只是调用你系统里已安装的 go 命令；只要终端里 go run main.go 能成功，VSCode 就一定能跑起来——卡住的地方几乎全在环境链断点上。
为什么 go run 在终端能跑，但在 VSCode 里按 Ctrl+F5 就失败？
这是最常被误判为“插件没装好”的问题。真实原因通常是：go 命令在 VSCode 内置终端里根本不可见。
- Windows：图形界面双击启动 VSCode 时，不会继承系统 PATH 中的
go路径（哪怕你确认go version在 CMD/PowerShell 里正常）；检查go env GOROOT输出的路径是否在系统环境变量PATH中（常见路径如C:\Program Files\Go\bin或%USERPROFILE%\go\bin） - macOS/Linux：VSCode 不自动加载
~/.zshrc或~/.bash_profile；必须从终端执行code .启动，才能继承 shell 环境 - 验证方式：在 VSCode 内置终端（
Ctrl + `）中直接运行which go和go env GOPROXY；两个都必须有合理输出，否则后续全部失效
go mod init 必须在项目根目录执行，且该目录要被 VSCode “打开”
VSCode 的 Go 扩展依赖模块根识别——不是“有 main.go 就行”，而是必须存在 go.mod 文件，且 VSCode 当前打开的是这个文件所在目录。
- 错误做法：新建一个空文件夹 → 直接写
main.go→ 在 VSCode 里只打开这个文件（没打开文件夹）→gopls状态栏显示 “Initializing…” 卡死 - 正确流程：在终端进入目标文件夹 → 运行
go mod init myapp（模块名可任意）→ VSCode 选择“文件 → 打开文件夹”，选中该目录 → 此时go.mod出现在资源管理器中，gopls才会真正启动 - 如果项目已有子目录（如
cmd/myapp/main.go），go mod init仍要在最外层根目录执行，不要进cmd里初始化
调试失败报 could not launch process: fork/exec : no such file or directory
这不是代码问题，是 launch.json 的 program 字段写错了——VSCode 默认模板把它设成 "${workspaceFolder}"，但 Go 调试器需要明确指向一个 .go 文件路径。
- 手动创建
.vscode/launch.json，确保program是具体文件路径，例如："${workspaceFolder}/main.go"（单文件项目）或"${workspaceFolder}/cmd/myapp/main.go"（多包结构） - 绝对不要写成目录路径（如
"${workspaceFolder}"）、二进制名（如"./main"）或漏掉.go后缀 - 如果程序依赖环境变量（如
CONFIG_PATH），必须在launch.json的env字段中显式声明；终端里设置的变量不会自动继承到调试进程
gopls 卡在 Initializing 或跳转失效，别急着重装插件
gopls 是 Go 扩展背后的语言服务器，它的行为异常往往和缓存、权限、代理三者有关，和插件本身关系不大。
- 先确认
GOBIN是否设置且可写：go env GOBIN若为空，运行go env -w GOBIN=$(go env GOPATH)/bin（macOS/Linux）或go env -w GOBIN=%USERPROFILE%\go\bin（Windows） - 检查该路径是否存在、当前用户是否有读写权限（
ls -ld $(go env GOBIN)或资源管理器查看） - 代理失效会导致
gopls静默卡住：运行go env GOPROXY，应返回类似https://goproxy.cn,direct；若为空或超时，补上go env -w GOPROXY=https://goproxy.cn,direct - 缓存损坏时，删掉对应平台的缓存目录：
$HOME/Library/Caches/gopls（macOS）、%LOCALAPPDATA%\gopls（Windows）、$XDG_CACHE_HOME/gopls（Linux），再重启 VSCode
最容易被忽略的一点：VSCode 启动方式决定环境变量是否生效，而几乎所有“找不到 go”“gopls 不工作”“调试路径错”的问题，根源都在这里——不是配置不对，是 VSCode 根本没拿到你预期的环境。
