根本原因是系统未将Go二进制目录加入$PATH；macOS/Linux需在~/.zshrc或~/.bash_profile中添加export PATH=$PATH:/usr/local/go/bin并source，Windows需手动添加C:\Go\bin到系统Path环境变量。
Go 1.21+ 安装后 go version 报错或命令未找到
根本原因通常是 PATH 没配对，尤其 macOS 和 Linux 用户容易忽略 shell 配置文件差异。Windows 用户则常把安装路径加到用户变量而非系统变量。
- macOS（zsh 默认）：把
export PATH=$PATH:/usr/local/go/bin加到~/.zshrc，然后运行source ~/.zshrc - Linux（bash）：加到
~/.bashrc；若用 systemd 启动终端（如某些桌面环境），可能需重启 session 或加到~/.profile - Windows：确认添加的是
C:\Go\bin（不是C:\Go），且修改的是“系统环境变量”，不是当前用户的 - 验证方式不是双击打开终端再输
go version，而是新开一个终端窗口执行——很多用户卡在这步，以为配置生效了，其实只是旧 shell 进程没重载
新建项目时 go mod init 报 module declares its path as 错误
这是 Go module 的路径校验机制在起作用：模块名必须和实际代码所在路径（或预期的 Git 仓库地址）一致，否则后续 go get 或构建会出问题。
- 如果项目在
~/projects/myapp，就该用go mod init github.com/yourname/myapp，而不是go mod init myapp - 本地开发不想绑 GitHub？可以用伪域名，比如
go mod init example.com/myapp，只要保证所有import路径与之匹配即可 - 已错误初始化怎么办？删掉
go.mod和go.sum，重新go mod init——别试图手动改module行，Go 工具链不认 - VS Code 里右键“Initialize Module”自动生成的路径常是错的，务必检查并修正
go build 成功但生成的二进制无法运行：no such file or directory
常见于 Linux/macOS 上交叉编译或静态链接缺失，本质是动态库依赖没打包进去。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 默认
go build生成的是动态链接可执行文件，依赖libc（Linux）或libSystem（macOS）。若在干净容器或不同发行版上运行失败，大概率是这个原因 - 解决办法：加
-ldflags '-s -w'去符号+去调试信息，再加CGO_ENABLED=0强制纯静态编译：CGO_ENABLED=0 go build -ldflags '-s -w' -o app - 注意：启用
CGO_ENABLED=0后，net包会用 Go 自研 DNS 解析器（不走系统 resolv.conf），os/user等依赖 cgo 的包将不可用 - Windows 用户遇到类似问题，通常是因为用了 Unix 风格路径（如
/tmp）硬编码在代码里，而 Windows 不识别
VS Code + Go 插件反复提示 “Failed to install tools”
这不是插件坏了，而是 Go 工具链下载被墙或代理配置不一致导致的典型症状。
立即学习“go语言免费学习笔记（深入）”；
- 不要点插件弹窗里的 “Install All”，它会按默认 GOPROXY（
https://proxy.golang.org）去拉工具，国内基本失败 - 先在终端运行
go env -w GOPROXY=https://goproxy.cn,direct（或https://goproxy.io），再重启 VS Code - 插件需要的工具如
gopls、dlv、goimports，都可以手动装：go install golang.org/x/tools/gopls@latest，注意路径是否在$GOPATH/bin且已加入 PATH - 如果用了非标准 GOPATH（比如改过
go env -w GOPATH=xxx），插件可能仍读旧路径，得同步更新 VS Code 设置里的"go.gopath"字段
go run 根本不认 import。 
