go version报command not found主因是PATH未生效，需source配置文件（macOS/Linux）或重启终端（Windows），再用echo $PATH或echo %PATH%验证是否含Go的bin路径。
go version 验证失败：PATH 没生效，别急着重装
安装完 Go 后执行 go version 报 command not found，大概率不是安装出错，而是 shell 没读到新 PATH。macOS/Linux 用户常漏掉 source ~/.zshrc（或 ~/.bashrc）；Windows 用户双击 .msi 安装后必须新开一个 PowerShell 或 CMD 窗口——旧终端不会自动继承新环境变量。
验证方法：先运行 echo $PATH（macOS/Linux）或 echo %PATH%（Windows），确认输出里含 /usr/local/go/bin（macOS/Linux）或 C:\Program Files\Go\bin（Windows 默认路径）。没出现就说明环境变量没写对或没生效。
- macOS M1/M2 用户用 Homebrew 安装时，PATH 要加
/opt/homebrew/bin，不是/usr/local/bin - Linux 手动解压安装的，
sudo tar -C /usr/local -xzf go*.tar.gz后，PATH 必须指向/usr/local/go/bin，少个/bin就失效 - VS Code 里终端不认
go？重启整个 VS Code，不只是关掉再开终端面板
go mod init 初始化失败：模块名不能带空格或中文
go mod init 报错 invalid module path，基本是模块名用了非法字符。Go Modules 要求模块路径符合导入规则：只能含字母、数字、下划线、短横线，且必须以字母开头，不能有空格、中文、点号（.）或大写字母（虽然不报错但不推荐）。
比如 go mod init my project 或 go mod init 项目名 都会失败；go mod init github.com/yourname/my-project 是安全的。
立即学习“go语言免费学习笔记（深入）”；
- 本地实验项目可直接用
go mod init example.com/hello，不用非得绑 GitHub - 如果项目目录在桌面（
~/Desktop/my app），先cd进去再 init，别用带空格的路径名 -
go.mod生成后，第一行module声明不可手动改——改了会导致go build找不到包
VS Code Go 插件不工作：gopls 启动卡住或提示“no workspace”
装完 VS Code 的 Go 插件（官方那个 “Go by Go Team”），打开 main.go 却没语法高亮、跳转、补全，常见原因是 gopls（Go language server）没起来，或工作区没识别为 Go 项目。
关键检查点：gopls 依赖 go 在 PATH 中可用，且项目根目录下必须有 go.mod 文件（哪怕只有一行 module xxx）。没有 go.mod，gopls 会退化为纯文本模式。
- VS Code 设置里搜 “go.toolsEnvVars”，确认没手动覆盖
GOPATH或GOROOT——现代 Go 不需要设GOPATH，设了反而干扰 - 右下角状态栏点 “No workspace” → “Add Folder to Workspace”，确保打开的是含
go.mod的文件夹，不是父目录 - 插件日志里看到
failed to load packages？删掉go.sum和vendor/（如果有），再go mod tidy重拉一遍依赖
go run 和 go build 行为差异：为什么本地能跑，部署后报 missing module
go run main.go 成功，但 go build 出来的二进制在另一台机器运行时报 cannot find module，问题不在代码，而在构建方式和模块依赖范围。
go run 只需当前目录下有 go.mod 就能解析 import；go build 默认也这样，但如果目标机器没装 Go、没配置 GOPROXY，且你的模块用了私有仓库或本地 replace，就会失败。
- 生产构建务必用
go build -ldflags="-s -w"去符号、减体积，再加CGO_ENABLED=0确保静态链接（避免 libc 版本冲突） - 私有模块（如
git.internal.company.com/lib）必须配GOINSECURE或公司级 GOPROXY，否则go build无法拉取 - 本地
replace仅对当前开发生效，go build时不会自动应用——想打包时用本地代码，得提前go mod edit -replace并提交go.mod
真正麻烦的从来不是装 Go，而是环境变量、模块路径、工具链协同这三者之间微妙的依赖关系。一次配置不对，后续所有命令都像蒙着眼走路——建议每步之后都用 go env 看实际生效值，比猜省力得多。
