go version报错“不是内部或外部命令”说明PATH未配置Go的bin目录，需手动将/usr/local/go/bin（macOS/Linux）或C:\Go\bin（Windows）加入环境变量并重启终端验证。
go version 命令报错：不是内部或外部命令
说明系统根本没识别到 go 命令，本质是 PATH 没包含 Go 的 bin 目录。这不是 Go 没装好，而是环境变量没生效。
- Windows 用户装完 .msi 后，必须重启终端（CMD/PowerShell）——旧终端不会自动加载新 Path
- macOS/Linux 用户如果用
brew install go，通常没问题；但手动解压安装的，得确认是否执行了echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.zshrc && source ~/.zshrc - 检查路径是否含中文、空格或特殊符号（比如
C:\Users\张三\go），这类路径会导致 Go 工具链静默失败 - 别信“安装完就自动好了”——亲手运行
echo $PATH（macOS/Linux）或echo %PATH%（Windows），搜一下有没有go/bin路径
go mod init 报错：cannot find module providing package
这是新手初始化项目时最常卡住的地方，根本原因不是代码写错了，而是当前目录不在模块感知范围内。
- 确保你在空目录里执行
go mod init example.com/hello，而不是在$GOPATH/src下硬套老模式 - 项目名不能是纯数字、不能以点开头、不能含大写字母（如
GoDemo会变成gdemo），推荐全小写+短横线，比如my-first-go-app - 如果已有
go.mod文件但内容异常，直接删掉它再跑一次go mod init—— 不要手改，Go 会自动生成正确格式 - 某些 IDE（如老版本 VS Code）会在后台偷偷创建隐藏模块，关掉编辑器再试一次更干净
VS Code 提示 “gopls not found” 或无法跳转定义
gopls 是 Go 官方语言服务器，不是可选插件，而是现代 Go 开发的基础设施。缺它，补全、悬停、重构基本瘫痪。
- 先运行
go install golang.org/x/tools/gopls@latest，注意不是go get（已废弃） - 装完后检查
gopls是否在PATH里：which gopls（macOS/Linux）或where gopls（Windows） - VS Code 的 Go 扩展设置里，确认
"go.goplsPath"没被手动填错——留空即可，它会自动找 - 如果用了代理，
gopls安装可能超时，临时加环境变量：export GOPROXY=https://goproxy.cn（国内用户）
go run main.go 却提示 “package main is not a main package”
Go 对入口文件有硬性要求：必须是 package main，且文件里必须有 func main()。但错误往往藏在细节里。
立即学习“go语言免费学习笔记（深入）”；
- 文件名别叫
main_test.go—— 以_test.go结尾的文件会被 Go 当作测试文件忽略 - 确认没有多余空行或 BOM 字符（尤其 Windows 记事本保存时容易带 BOM），用 VS Code 或 Vim 打开，状态栏看编码是否为 UTF-8 without BOM
- 如果项目里有多个
.go文件，go run默认只跑当前目录下所有.go文件；但如果有init()函数 panic，也会导致这个报错，建议先go build看具体错误 - 别在
src子目录里建main.go—— Go Modules 模式下，项目根目录就是模块根，main.go应该放在顶层
go mod 默认不读 GOPATH，gopls 默认不走代理，go run 默认不认测试文件——这些不是 bug，是设计选择，但初学者最容易在这些默认值上栽跟头。 
