go command not found是PATH未配置的直接信号，需确认Go安装路径（如/usr/local/go/bin或C:\Go\bin）并添加到系统PATH，Zsh用户改~/.zshrc、Bash用户改~/.bashrc、Windows用户在环境变量中添加，保存后source生效并运行go version验证。
go command not found：PATH没配对
这是环境变量配置失败最直接的信号。系统根本找不到 go 命令，说明安装路径没进 $PATH。
- 先确认 Go 实际安装位置：
ls -l /usr/local/go/bin/go（macOS/Linux）或检查C:\Go\bin\go.exe（Windows）是否存在 - Zsh 用户（macOS Catalina+、多数 Linux）编辑
~/.zshrc，追加：export PATH="/usr/local/go/bin:$PATH" - Bash 用户改
~/.bashrc或~/.bash_profile，内容同上 - Windows 用户在「系统属性 → 高级 → 环境变量」中，把
C:\Go\bin加入用户或系统级Path - 改完必须重载配置：
source ~/.zshrc，再运行go version验证
failed to load mod file：GO111MODULE=on 但没 go.mod
不是模块本身坏了，是当前目录没有 go.mod，而 go get 又拒绝在非模块上下文里写依赖。
- 想初始化新项目？先执行：
go mod init example.com/myapp（模块名可任意，不需真实存在） - 只是装工具（比如
gopls）？加-d参数跳过构建：go install golang.org/x/tools/gopls@latest -d - 误在
$GOPATH/src下执行了命令？Go 1.16+ 默认禁用 GOPATH 模式，退出该目录，换到空目录再试 - 别手动设
GOROOT—— 安装程序自己会识别，错设反而导致构建失败
cannot find package 或 dial tcp timeout：代理和模块模式没开
国内拉不到 golang.org/x 等包，本质是网络策略和模块开关没对齐。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 必须开启模块：
go env -w GO111MODULE=on - 必须配代理：
go env -w GOPROXY=https://goproxy.cn,direct（七牛云）或https://mirrors.aliyun.com/goproxy/（阿里云） - 私有仓库要跳过代理？设
go env -w GOPRIVATE=git.company.com - 验证是否生效：
go env | grep GOPROXY，输出应含你设置的地址 - 如果仍超时，可能是
GOSUMDB卡住，可临时关掉：go env -w GOSUMDB=off（仅调试用）
build xxx: cannot find module yyy：go.mod 识别失败或缓存污染
go.mod 文件存在，但 Go 就是“视而不见”，常见于路径混乱、缓存错乱或初始化不完整。
立即学习“go语言免费学习笔记（深入）”；
- 确认项目根目录下有
go.mod，且你在该目录下执行命令（pwd看一眼） - 路径不能含中文、空格或特殊符号；不要放在
$GOPATH/src里（除非刻意用旧模式） - 运行
go mod tidy自动补依赖、删冗余；它会报出具体缺失项，比盲目go get更可靠 - 缓存损坏？清掉：
go clean -modcache，再重试 - 如果用 VS Code 或 GoLand，重启编辑器窗口（Reload Window），否则 LSP 可能还卡在旧状态
~/.zshrc 忘了 source，或者开了 GO111MODULE=on 却没配 GOPROXY，结果报错信息全指向依赖本身，实际根源在上游配置。 
