必须先确保 go version 和 go env 能正常输出，否则后续配置无效；go version 验证 Go 是否安装并加入 PATH，go env 检查 GOPATH、GOROOT 是否有明确路径，zsh 用户需修改 ~/.zshrc 并 source，go mod init 应在任意干净目录执行而非 $GOPATH/src，VS Code 需手动安装 gopls，GOPROXY 推荐设为 https://goproxy.cn,direct。
go version 和 go env 必须先跑通
没这俩命令的输出，后面所有配置都是空中楼阁。很多人卡在“VS Code 里点运行没反应”，其实根本不是编辑器问题，而是终端里 go version 都报 command not found。
检查要点：
-
go version要能立即输出类似go version go1.23.4 linux/amd64的结果 -
go env GOPATH和go env GOROOT都得有明确路径，不能是空值或unknown - 如果用 zsh（macOS 10.15+ / Linux 默认），确认改的是
~/.zshrc而非~/.bashrc；改完必须source ~/.zshrc，重启终端不等于重载配置
go mod init 不要放在 $GOPATH/src 里执行
这是老教程遗留的最大坑。Go 1.16+ 默认启用模块模式，go mod init 的位置决定项目根目录，而它和 $GOPATH 没关系。硬塞进 $GOPATH/src 反而会触发兼容模式，导致 go get 行为异常、依赖路径错乱。
正确做法：
立即学习“go语言免费学习笔记（深入）”；
- 随便找个干净目录，比如
~/projects/myapp，直接go mod init github.com/yourname/myapp -
go.mod生成后，go run .就能跑通，不需要任何额外路径设置 - 如果项目已有
go.mod，就别再go mod init—— 重复初始化会覆盖原有 module 名
vscode-go 插件依赖 gopls，但 gopls 不自动装
VS Code 装了 Go 扩展，不代表 gopls（Go Language Server）就存在。插件启动时发现找不到 gopls，就会静默降级为基础语法高亮，没有跳转、补全、诊断功能。
手动装一次，一劳永逸：
- 终端执行
go install golang.org/x/tools/gopls@latest - 装完后，在 VS Code 里按
Cmd+Shift+P（macOS）或Ctrl+Shift+P（Windows/Linux），输入Go: Install/Update Tools，勾选gopls再点 OK - 重启 VS Code，打开
main.go，看状态栏左下角是否显示gopls和版本号
GOPROXY 设置不当会导致依赖拉取失败或超慢
国内直连 proxy.golang.org 基本不可用，但设错代理又可能让 go mod download 卡死或返回 403。不是加个 URL 就完事，顺序和 fallback 很关键。
推荐配置（2026 年实测有效）：
-
go env -w GOPROXY=https://goproxy.cn,direct（大陆首选） - 或更稳一点：
go env -w GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct - 绝对不要只写
https://proxy.golang.org—— 它在国内基本不可达，direct在前会导致模块校验失败 - 设完后删掉
go.sum和go mod download -dirty，再go mod tidy触发重新拉取
真正卡住人的，往往不是“怎么装”，而是某个环境变量没生效、某个二进制没装进 PATH、或者代理链路里漏了一个 direct。每一步都建议用命令验证，而不是凭感觉往下走。
