必须用官方二进制包安装go（禁用系统包管理器），go 1.21+为硬性门槛；安装后需正确配置path（linux/macos写入shell配置并source，windows加系统级path）、goproxy（go env -w goproxy=https://goproxy.cn,direct）、gobin或gopath/bin路径，并在module根目录下执行go run。
Go 环境装不对，后续所有依赖、工具链、框架（比如 go-zero、goctl）都会卡在第一步。核心结论很明确：别用系统包管理器装 Go，优先用官方二进制包；Go 1.21+ 是硬门槛，低于这个版本，go-zero、PGO、模糊测试等关键能力直接不可用。
go version 输出异常或提示 command not found
这是最常见也最容易被忽略的环境变量问题。安装完官方二进制包后，go 命令找不到，根本不是没装好，而是 PATH 没生效。
- Linux/macOS：确认是否执行了
export PATH=$PATH:/usr/local/go/bin（或你解压的实际路径），且该行已写入~/.bashrc或~/.zshrc，然后运行source ~/.zshrc（别漏这步） - Windows：必须手动把
GOROOT\bin加进系统级Path环境变量，仅用户级无效；验证时用新打开的 CMD/PowerShell，旧窗口不继承新变量 - VS Code 中终端仍报错？重启整个 VS Code，它不会自动重载 shell 的
PATH
go get 或 go install 失败：timeout 或 no matching versions
国内直连 proxy.golang.org 几乎必然失败。这不是网络问题，是 Go Modules 默认代理策略导致的。
- 必须设置国内代理：运行
go env -w GOPROXY=https://goproxy.cn,direct（注意,direct不可省，否则私有模块无法拉取） - 验证是否生效：执行
go env GOPROXY，输出应为https://goproxy.cn,direct - 如果项目用了
go mod vendor，记得更新 vendor 前先确保代理已设好，否则go mod vendor会静默失败并留下空目录
goctl 安装后提示 command not found
goctl 是二进制工具，不是脚本，它依赖 GOBIN 或默认 $GOPATH/bin 路径。很多人装完不配置，就以为工具坏了。
- 先确认安装命令是否带
@latest：正确命令是go install github.com/zeromicro/go-zero/tools/goctl@latest（缺@latest会装失败但无报错） - 检查
GOBIN：运行go env GOBIN，若为空，说明它默认指向$GOPATH/bin；确保$GOPATH/bin已加入PATH - 快速验证：执行
ls $(go env GOPATH)/bin/goctl，文件存在但命令不可用，就是PATH没包含该路径
go run main.go 报错：module xxx is not in GOROOT
这是 Go Modules 启用后最常见的误解——误以为 Go 还像老版本一样靠 GOPATH 找代码。实际从 Go 1.16 起，默认启用 Modules，go run 必须在 module 根目录下执行。
- 错误做法：在任意目录下新建
main.go就跑go run main.go - 正确流程：先
go mod init example.com/myapp初始化 module，再go run main.go - 如果已有
go.mod但报错，检查当前目录是否是go.mod所在目录（可用pwd和ls go.mod确认） - 编辑器里右键“Run”失败？多数是因为工作区没设对目录，VS Code 需以含
go.mod的文件夹为根打开项目
真正容易被忽略的点不在安装步骤本身，而在环境变量和模块作用域的边界上：PATH 没刷新、GOBIN 没生效、go.mod 目录层级错位——这些都不是“不会装”，而是“以为装完了，其实只走了一半”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
