Go开发环境就绪需满足三要素：安装go命令并配置PATH、手动安装gopls语言服务器且其路径加入PATH、项目根目录执行go mod init生成go.mod；缺一不可，否则VSCode无法语法高亮、跳转定义或调试。
Go 环境不是装完 go version 就算完事——go run 能跑，不代表 VSCode 能跳转、go mod 能识别、dlv 能调试。真正卡住新手的，是工具链没闭环。
go version 能输出 ≠ Go 开发环境就绪
很多用户执行 go version 成功后直接打开 VSCode 写 main.go，结果发现：语法不高亮、fmt 标红、Ctrl+Click 跳不到定义。这不是代码问题，是语言服务器 gopls 没起来。
-
gopls不随 Go 安装包自带，必须手动安装：go install golang.org/x/tools/gopls@latest - 安装后二进制默认在
$GOPATH/bin/gopls（Windows 是%GOPATH%\bin\gopls.exe），该路径必须在系统PATH中 - 网络受限时先设代理：
go env -w GOPROXY=https://goproxy.cn,direct，再装gopls - VSCode 底部状态栏看到
gopls (running)才算真正就位，(starting)或空白说明失败
go mod init 是硬门槛，不是可选项
空文件夹里只放一个 main.go，VSCode 会认为“no workspace detected”，所有智能提示、依赖分析、测试运行功能全部降级为纯文本编辑。
- 必须在项目根目录执行：
go mod init example.com/myapp（模块名任意，但建议用域名格式） - 执行后生成
go.mod和go.sum，VSCode 才能识别项目边界和依赖范围 - 别把项目放在
$GOPATH/src下硬套旧习惯——现代 Go 不依赖GOPATH，VSCode 设置里go.gopath留空更安全 - 已建好文件夹但忘了初始化？终端进该目录补
go mod init即可，VSCode 通常几秒内自动重载
F5 调试失败，大概率是上下文错了
常见报错如 "could not launch process: fork/exec ./main: no such file or directory"，或断点完全不生效，往往不是配置问题，而是 VSCode 没找到可执行入口。
立即学习“go语言免费学习笔记（深入）”；
- 按 F5 前，确保编辑器焦点在含有
package main和func main()的文件上（通常是main.go） - 不要在
go.mod、go.sum或其他非源码文件上按 F5 - 确认
dlv已安装：go install github.com/go-delve/delve/cmd/dlv@latest，且其路径也在PATH中 - 首次调试弹出配置提示时，选
"Go: Launch Package"即可，自动生成.vscode/launch.json
go run 能跑，但 go build 出来的二进制 panic，问题出在模块上下文
典型错误是 panic: failed to initialize module 或读不到 embed 文件——这不是编译失败，而是构建时没带上模块元信息。
- 确认构建命令是否在模块根目录（即有
go.mod的目录）下执行 - 别用
go build ./ -o app这种模糊路径，改用go build -o app .（点号表示当前模块） - 如果用了
runtime/debug.ReadBuildInfo()或embed.FS，它们依赖模块信息，脱离模块根构建就会失效 - CI/CD 脚本里尤其要注意工作目录，
cd到模块根再go build
最易被忽略的点：工具链各组件（gopls、dlv、go）的 PATH 必须全部生效，且版本兼容；go.mod 是项目身份的唯一凭证，不是装饰品；调试前的焦点文件和工作目录，比 launch.json 配置更重要。
