真正可靠的Go环境需满足：关终端重开后go version和go run均稳定，go mod tidy不卡代理、无路径冲突；核心是PATH生效、GO111MODULE=on、GOPROXY/GOPRIVATE正确配置且持久化，gopls依赖go.mod存在及模块根目录打开。
go 命令能跑起来，不等于环境真搭好了——多数人卡在「看似可用、实则脆弱」的状态，比如 go mod init 静默失败、gopls 启动报错、依赖拉不到、跨终端失效。真正可靠的环境，是关掉终端再开，go version 和 go run main.go 都稳，且 go mod tidy 不卡代理、不报路径冲突。
go command not found 的真实原因和验证方式
不是安装包没点完，而是 PATH 没生效或指向错误路径。
- macOS/Linux：别只信
which go，要跑echo $PATH看输出里有没有/usr/local/go/bin（pkg 安装）或$HOME/local/go/bin（手动解压）；若没有，检查~/.zshrc或~/.bash_profile里export PATH=...是否写错变量名（比如把$GOROOT写成$GOOROOT） - Windows：PowerShell 里用
Get-Command go，不是where go；若失败，去「系统属性 → 高级 → 环境变量」里确认C:\Program Files\Go\bin（或你自定义的路径）确实在「系统变量」或「用户变量」的Path列表中，且没拼错斜杠（Windows 用反斜杠，但 PATH 里允许正斜杠） - 统信UOS等国产系统：APT 安装后可能只设了
GOROOT，没自动加PATH，必须手动补export PATH=$PATH:/usr/lib/go/bin（路径以dpkg -L golang | grep bin实际查到的为准）
go mod init 失败的三个隐藏条件
它不报错，但生成空 go.mod 或 module 名乱码，本质是当前目录触发了旧模式 fallback。
- 当前路径不能在
$GOPATH/src下——哪怕你根本没设GOPATH，只要目录结构形如~/go/src/github.com/user/proj，go mod init就会试图按 GOPATH 规则推导 module 名，结果常为github.com/user/proj而非你想要的myproj -
GO111MODULE必须为on：老脚本或 CI 环境可能关着，执行go env -w GO111MODULE=on强制启用（Go 1.16+ 默认开启，但某些 shell 初始化脚本会覆盖） - 项目根目录下不能有
vendor/目录——即使它是空的，go mod init也会跳过模块初始化；删掉再试
VS Code 中 gopls 启动失败的硬性前提
gopls 不是插件装上就活，它依赖三个底层就绪：
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
-
go命令本身必须可执行且版本 ≥ 1.18（gopls0.13+ 要求），运行go version确认 - 项目根目录必须有
go.mod文件（go mod init生成），且文件不能为空或语法错误 - 打开的文件必须是
.go后缀，且所在目录是模块根目录（即含go.mod）——VS Code 打开单个main.go文件却不打开整个文件夹，gopls就不会加载
国内开发绕不开的 GOPROXY 和 GOPRIVATE
不配代理，go get 和 go mod tidy 会卡死或超时；但全走代理又可能漏掉私有仓库。
立即学习“go语言免费学习笔记（深入）”；
- 推荐配置：
go env -w GOPROXY=https://goproxy.cn,direct（direct表示对未匹配域名的请求直连，避免私有 GitLab 地址被代理） - 如果公司用内网 GitLab，加
go env -w GOPRIVATE=gitlab.example.com，这样gitlab.example.com/my/project就绕过代理走 SSH/HTTPS 直连 - 验证代理是否生效：运行
go env GOPROXY，输出应为完整 URL 字符串，不是off或空
export GOPROXY=... 只影响当前 shell，VS Code 图形界面启动时并不会继承这个值。必须用 go env -w 写入全局配置，或者在 VS Code 的 settings.json 里显式指定 "go.toolsEnvVars"。 
