根本原因是PATH未包含Go的bin目录；macOS/Linux需将/usr/local/go/bin加入~/.zshrc并source，Windows需在系统环境变量Path中添加C:\Go\bin，然后新开终端验证go version。
Go 安装后 go version 报错：command not found
根本原因是系统没把 Go 的 bin 目录加进 $PATH。macOS/Linux 默认装在 /usr/local/go，Windows 装在 C:\Program Files\Go\bin，但 shell 启动时根本不知道这个路径。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- macOS/Linux：在
~/.zshrc（或~/.bash_profile）末尾加一行export PATH=$PATH:/usr/local/go/bin，然后执行source ~/.zshrc - Windows：右键“此电脑”→“属性”→“高级系统设置”→“环境变量”，在“系统变量”里找到
Path，点“编辑”，新增一条C:\Program Files\Go\bin - 验证方式不是重启终端，而是新开一个终端窗口再跑
go version—— 很多人卡在这一步，以为 source 了就生效，其实旧终端不会自动 reload
用 go mod init 初始化项目却提示 “cannot find module root”
这不是 Go 版本问题，而是当前目录不在 GOPATH 且没 git 仓库信息，go mod init 无法推导模块路径。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 最稳妥做法：先
git init，再go mod init example.com/myapp（模块名建议用域名+项目名，别用main或本地路径） - 如果不想立刻 git，可显式指定模块路径：
go mod init myproject，但后续发布到远程仓库时得手动改go.mod里的 module 行 - 注意：不能在
$GOPATH/src下直接go mod init，Go 1.16+ 默认关闭 GOPATH 模式，混合使用会触发冲突
go run main.go 提示 “no required module provides package …”
这是模块感知开启后最常见的报错，说明 Go 找不到依赖的包，但更可能是你还没运行过 go mod tidy，或者 go.mod 里压根没声明依赖。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先确认
go.mod存在且第一行是module xxx；如果没有，回到上一节重新初始化 - 有 import 但没下载依赖？直接运行
go mod tidy，它会自动补全require并下载对应版本 - 如果用了私有模块（比如公司内网 Git），得提前配置
GOINSECURE或GOPRIVATE，否则tidy会卡住或报 403 - 别手动编辑
go.sum—— 它是校验文件，改了会导致后续go build失败
VS Code 里写 Go，gopls 总是崩溃或提示 “no workspace”
VS Code 的 Go 插件默认依赖 gopls（Go Language Server），但它只在打开真实模块根目录时才正常工作 —— 单个 .go 文件、空文件夹、或子目录都会让它降级为“无语言功能”状态。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 务必用 VS Code **打开整个模块根目录**（即含
go.mod的文件夹），不要只打开main.go - 如果
gopls还报错，先在终端运行go install golang.org/x/tools/gopls@latest更新服务端 - 检查 VS Code 设置里是否关掉了
"go.useLanguageServer": true（默认开启，关了就只剩基础高亮） - Windows 用户遇到路径大小写问题（比如盘符是
c:不是C:），gopls可能静默失败，统一用小写盘符重开文件夹
go.mod 生成时机、gopls 对目录结构的强依赖——这些不是安装步骤里的“额外操作”，而是 Go 生态本身的设计前提。漏掉任意一个，后面写代码时的问题都会变得更难定位。 
