go version报错或无输出说明path未包含go的bin目录，windows需手动添加d:\go\bin，macos/linux需在~/.zshrc或~/.bash_profile中配置export path=$path:/usr/local/go/bin并source生效。
go version 命令报错或返回空，说明环境变量没配对
常见现象是 go version 提示 command not found 或直接无输出。根本原因不是 Go 没装，而是 PATH 没包含 D:\Go\bin（Windows）或 /usr/local/go/bin（macOS/Linux）。
实操建议：
- Windows：确认安装时勾选了“Add Go to PATH”，若没勾选，手动把
D:\Go\bin加进系统环境变量PATH；命令行重启后验证 - macOS/Linux：检查
~/.zshrc或~/.bash_profile是否有export PATH=$PATH:/usr/local/go/bin，执行source ~/.zshrc生效 - 别信“安装完就可用”——哪怕用 .pkg/.msi 安装，某些版本（尤其 macOS M 系列）仍需手动补 PATH
go mod init 后 go get 失败，大概率是代理或网络策略问题
内网或企业防火墙环境下，go get github.com/gin-gonic/gin 会卡住或报 module github.com/gin-gonic/gin: Get "https://proxy.golang.org/..." 类错误。这不是你代码的问题，是 Go 默认依赖外网代理。
实操建议：
- 临时绕过：执行
go env -w GOPROXY=direct，强制直连（仅限能访问 GitHub 的环境） - 内网推荐：设私有代理，如
go env -w GOPROXY=http://172.31.33.33:8080,direct，末尾direct是 fallback，避免代理宕机时全挂 - 注意：Go 1.13+ 才支持逗号分隔多个代理，旧版本只能设单个；
GOPRIVATE必须同步设，比如go env -w GOPRIVATE=git.zhengxm.cn/*，否则私有域名仍走代理
go run main.go 成功但 go build -o xxx.exe 生成的二进制无法运行
典型表现是双击 exe 弹黑框闪退，或终端里报 failed to initialize module、找不到 runtime/cgo。这不是代码逻辑错，而是构建时没处理好 CGO 或平台约束。
实操建议：
- Windows GUI 程序想静默启动：必须加
-ldflags="-H=windowsgui"，例如go build -ldflags="-H=windowsgui" -o app.exe main.go - 交叉编译注意 CGO：Linux/macOS 上构建 Windows 二进制时，
CGO_ENABLED=0是安全选项，但会丢弃部分 C 依赖（如 sqlite、openssl），需权衡 - 检查
GOOS和GOARCH：默认构建当前平台，跨平台要显式设，如GOOS=linux GOARCH=amd64 go build -o server-linux main.go
go mod vendor 后依赖不全，或 vendor 目录下出现重复包
go mod vendor 后运行 go build -mod=vendor 仍报 cannot find module，或者 vendor/ 里同时存在 github.com/sirupsen/logrus@v1.9.3 和 @v1.11.0 —— 这说明 vendor 没真正“冻结”依赖树。
实操建议：
- 先确保
go.mod干净：执行go mod tidy清理冗余依赖，再go mod vendor - vendor 不自动递归拉取间接依赖：如果 A 依赖 B，B 依赖 C，而 C 不在
go.mod显式 require，go mod vendor可能漏掉 C；此时需go list -m all | grep c确认，必要时手动go get c@version - 慎用
replace：本地 replace 路径在 vendor 里不会被展开，CI 环境会失效；真要隔离，用GOPRIVATE+ 私有模块仓库更可靠
GOPROXY 和 GOPRIVATE 的组合配置——只设代理不设私有域，私有包照样走代理失败；只设私有域不设代理，公网包又慢得无法忍受。两者必须成对出现，且值要严格匹配你的模块域名前缀。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
