Go环境默认不依赖GOPATH，go mod是唯一推荐方式；go version失败多因PATH未生效；go mod init失败常因路径含空格/中文或权限不足；import报错主因proxy未配置或版本不匹配；IDE提示包找不到通常是gopls未识别module root。
Go 环境现在默认不依赖 GOPATH，go mod 是唯一推荐的包管理方式；强行沿用旧式 GOPATH 工作区反而会触发冲突或模块查找失败。
go version 检查失败：不是“没装”，而是 PATH 没生效
执行 go version 报错 command not found，大概率不是 Go 没装，而是 bin 目录没加进 PATH。macOS/Linux 用户常漏掉 source ~/.zshrc（或 ~/.bash_profile）；Windows 用户则容易把 Path 写成 C:\Go\bin 但实际安装路径是 C:\Program Files\Go\bin。
- 验证安装路径：Linux/macOS 运行
ls -l /usr/local/go/bin/go或which go；Windows 在资源管理器里确认安装目录 - 临时测试：直接运行
/usr/local/go/bin/go version（替换为你的实际路径），成功说明只是 PATH 问题 - 修正 PATH 后，新开终端再试 —— 不要只在当前终端里改完就以为生效了
go mod init 失败：当前目录含空格、中文或权限不足
go mod init 报错 no such file or directory 或 permission denied，常见于三种情况：目录名带空格（如 my go project）、含中文路径（如 /Users/张三/code）、或当前用户对父目录无写权限（尤其在 /opt 或系统级路径下）。
- 新建项目务必用纯英文、无空格路径：
mkdir ~/projects/hello-go && cd ~/projects/hello-go - 避免在
/tmp或挂载的网络盘操作 ——go mod会生成go.sum和写缓存，这些位置可能拒绝持久化写入 - 若用
sudo go mod init，后续所有go build都得加sudo，这是典型权限陷阱
import 第三方包报错：proxy 配置缺失或版本不匹配
执行 go run main.go 时卡在 go: downloading github.com/some/pkg v1.2.3，或报错 cannot find module providing package，本质是模块代理或版本解析失败。
立即学习“go语言免费学习笔记（深入）”；
- 国内用户必须配代理：
go env -w GOPROXY=https://goproxy.cn,direct（注意末尾direct不可省） - 检查
go.mod中依赖是否写错：比如误写import "github.com/gin-gonic/gin/v2"，但实际应为"github.com/gin-gonic/gin"（v2+ 版本需用/v2子路径） - 若引用私有仓库，需额外配置
GOINSECURE或git config的 URL 重写规则，否则go get会拒接 HTTPS 以外协议
IDE 提示 “package not found”：gopls 没读到正确的 module root
VS Code 或 GoLand 显示红色波浪线，提示 cannot find package，但命令行 go run 正常 —— 这是编辑器语言服务器（gopls）没识别到 go.mod 所在目录为项目根。
- 确保打开的是
go.mod所在目录（不是它的父目录或子目录），VS Code 中看左下角状态栏是否显示Go (module) - 重启
gopls：Cmd/Ctrl+Shift+P → 输入 “Go: Restart Language Server” - 禁用 GOPATH 模式：IntelliJ IDEA 中关闭
Settings → Go → GOPATH里的 “Enable GOPATH mode”，现代项目不需要它
真正麻烦的从来不是装 Go，而是路径、代理、权限、IDE 缓存这四层叠加的静默失效 —— 它们不会报明确错误，只会让 import 不亮、build 不起、debug 断点无效。动手前先 go env 看一眼真实配置，比反复重装快得多。
