go version报错需检查PATH是否生效：Windows重启终端或手动添加Go安装路径到系统环境变量，macOS/Linux编辑shell配置文件并source；GOPATH从Go 1.11起非必需，但go install等场景仍需手动设置；go mod init应避免在$GOPATH/src下操作，模块名须小写、无空格、不以数字开头；国内需配置GOPROXY=https://goproxy.cn,direct并验证生效。
go version 命令报错或不识别？检查 PATH 是否真生效
安装完 Go 后，go version 报 'go' 不是内部或外部命令（Windows）或 command not found: go（macOS/Linux），说明 PATH 没写对或没刷新。MSI 安装包勾选了 “Add Go to PATH”，但 Windows 有时不会立即同步到所有已打开的终端；macOS/Linux 则常因 shell 配置文件未 source 而失效。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Windows：关闭所有 cmd/PowerShell/VS Code 终端，重新打开，再试
go version；若仍失败，手动检查系统环境变量中Path是否含C:\Program Files\Go\bin（或你自定义的安装路径） - macOS/Linux：确认当前 shell 类型（
echo $SHELL），编辑对应配置文件（~/.zshrc或~/.bash_profile），确保有export PATH=$PATH:/usr/local/go/bin；执行source ~/.zshrc后再验证 - 别信“安装完就自动可用”——重启终端或重新登录用户会更稳妥
go env GOPATH 返回空或默认路径？是否需要手动设
从 Go 1.11 开始，go mod 是默认模式，GOPATH 对新项目已非必需。但如果你用 go install 安装 CLI 工具（如 clawusage）、或维护老项目、或某些 IDE 插件依赖 GOPATH 结构，就必须显式设置。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Windows：用“系统属性 → 高级 → 环境变量”新建系统变量
GOPATH，值设为纯英文路径（如D:\gopath），再往Path加%GOPATH%\bin - macOS/Linux：在
~/.zshrc中加export GOPATH=$HOME/go，并确保$GOPATH/bin在PATH中靠前位置 - 验证：运行
go env GOPATH和go env GOBIN，二者应指向同一层级下的bin目录；否则go install生成的二进制可能找不到
go mod init 初始化失败？常见路径和命名陷阱
go mod init 失败往往不是 Go 本身问题，而是当前目录或模块名触发了隐式约束。比如在 $GOPATH/src 下执行，Go 会尝试推导旧式 import 路径；模块名含空格、大写字母或以数字开头，也会被拒绝。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 不要在
$GOPATH/src内初始化新项目——现代 Go 项目可放在任意目录，比如~/projects/myapp - 模块名用小写字母+连字符，推荐 GitHub 风格：
go mod init github.com/yourname/myapp；避免go mod init MyApp（首字母大写非法） - 如果提示
go.mod already exists，说明当前目录或父目录已有go.mod；用go mod graph | head -n 5可快速定位嵌套关系 - 首次
go run main.go时若卡在Fetching，大概率是代理问题，不是模块初始化失败
国内拉取依赖超时或失败？GOPROXY 必须配，且顺序不能错
不设 GOPROXY，go get 或 go mod download 默认直连 proxy.golang.org，国内多数情况会 404 或 timeout。设了但顺序不对（比如把 direct 放前面），会导致私有仓库无法命中。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 优先用国内镜像：
go env -w GOPROXY=https://goproxy.cn,direct（2026 年仍稳定）或https://mirrors.tuna.tsinghua.edu.cn/goproxy/ -
direct必须放在逗号分隔列表末尾，表示“以上都失败才直连”，否则私有模块（如公司内网 Git）永远走不通 - 临时禁用代理调试：加
-x参数看真实请求地址，例如go get -x github.com/sirupsen/logrus - VS Code 中 Go 扩展有时会忽略 shell 的
GOPROXY，需在设置里显式填入，或改用go env -w全局写入
真正容易被忽略的不是“怎么配”，而是“配完要不要验证”。每次改完环境变量或代理，务必新开终端跑 go env | grep -i proxy 和 go list -m all，前者确认配置落地，后者验证模块拉取链路通不通——这两步跳过，后面所有 go run、go test 都可能静默失败。
