go命令找不到、go mod报错、gopls启动失败，根本原因是环境变量（PATH、GOROOT、GOPROXY）配置错误或缺失，或IDE未正确继承shell环境，需按which go → go env GOROOT → go env GOPROXY → go mod download顺序逐项验证。
go 命令找不到，go mod 报错，gopls 启动失败——这些问题基本都卡在环境变量、模块代理或 IDE 集成这三块，不是 Go 本身难，而是配置链上某一处断了。
PATH 没配对，go 命令就不存在
这是最常见也最容易验证的问题。系统找不到 go，本质是 shell 根本没加载到它的可执行路径。
- 先确认 Go 是否真装到了预期位置：
ls -l /usr/local/go/bin/go（Linux/macOS）或dir C:\Go\bin\go.exe（Windows） - 再检查 PATH 是否包含该路径：运行
echo $PATH（macOS/Linux）或echo %PATH%（Windows CMD），看输出里有没有/usr/local/go/bin或C:\Go\bin - Zsh 用户改
~/.zshrc，Bash 用户改~/.bashrc或~/.bash_profile，Windows 用户必须走「系统属性 → 环境变量」面板，别只用set临时设 - 改完一定要重载：
source ~/.zshrc，然后立刻跑which go和go version验证
go mod 报 failed to load mod file
这不是依赖坏了，是你当前目录没有 go.mod，而 Go 拒绝在非模块上下文里写依赖。
- 如果想初始化新项目：直接在空目录下运行
go mod init example.com/myapp（模块名任意，不需真实存在） - 如果只是装工具（比如
gopls）：加-d参数跳过构建，例如go install golang.org/x/tools/gopls@latest；或者用GOBIN显式指定安装位置，避免污染默认$GOPATH/bin - 别在
$GOPATH/src下执行go get—— Go 1.16+ 默认禁用 GOPATH 模式，进了这个目录就自动降级，反而触发更多兼容性问题
国内拉不到 golang.org/x/ 包，gopls 卡死
直连 proxy.golang.org 在国内基本不可用，不设代理会导致 go mod download 卡住、IDE 插件反复报红、gopls 启动超时。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 必须设
GOPROXY：推荐export GOPROXY=https://goproxy.cn,direct（direct放末尾，否则私有模块无法直连） - 顺手设
GOSUMDB：国内建议用sum.golang.google.cn，避免校验和数据库访问失败 - VS Code 的
gopls继承 shell 环境变量，但 GoLand 必须进 Settings → Go → GOROOT → Reload 才会刷新代理配置 - 验证是否生效：
go env GOPROXY输出应为https://goproxy.cn，再试go mod download github.com/spf13/cobra，几秒内完成才算真正通了
GOROOT 设错导致构建失败
GOROOT 只应指向 Go 安装根目录（如 /usr/local/go），手动设错是高频翻车点，尤其容易和 GOPATH 混淆。
- 运行
go env GOROOT，看输出是否是你解压 Go 的真实路径；如果显示/home/user/go这类明显不对的路径，说明被错误覆盖了 - 搜遍所有 shell 配置文件（
~/.zshrc、~/.profile、/etc/profile），删掉类似export GOROOT=$HOME/go的行 - 检查项目根目录下有没有
.env或go.env文件偷偷覆盖了GOROOT - 官方
.pkg或.msi安装器会自动设好GOROOT，手动解压安装才需要显式配置——多数人其实不该碰它
真正麻烦的从来不是单个错误，而是多个配置项互相干扰：PATH 错了，go 都跑不起来；GOPROXY 没设，go mod 就卡死；GOROOT 被乱改，连 go build 都报奇怪的路径错误。查问题时别猜，按顺序验证 which go → go env GOROOT → go env GOPROXY → go mod download，链路一通，后面就顺了。
