go version不显示说明环境变量未生效，需检查$PATH是否包含/usr/local/go/bin（macOS/Linux）或C:\Go\bin（Windows），并确认$GOROOT指向正确安装路径，否则命令不可用。
Go 1.22+ 安装后 go version 不显示？检查 $PATH 和 $GOROOT
直接执行 go version 报错或无输出，大概率是环境变量没生效。macOS/Linux 下安装 Go 后，二进制默认放在 /usr/local/go/bin，但 shell 并不会自动把它加进 $PATH；Windows 则可能因安装时未勾选“Add to PATH”导致命令不可用。
验证方式：运行 which go（macOS/Linux）或 where go（Windows），若无输出，说明路径未配置。
- macOS/Linux：在
~/.zshrc或~/.bash_profile中添加export PATH="/usr/local/go/bin:$PATH"，然后source ~/.zshrc - Windows：手动将
C:\Program Files\Go\bin（或你自定义的安装路径）加入系统环境变量PATH - 额外确认：
echo $GOROOT应输出/usr/local/go（或对应路径），否则go命令可能调用失败或行为异常
初始化模块时 go mod init 报错 “working directory is not part of a module”？别急着删 go.mod
这个提示不是错误，而是提醒你当前目录还没初始化为 Go 模块——它只在首次运行 go mod init 时出现，且仅当项目根目录下没有 go.mod 文件时触发。
真正要警惕的是以下几种情况：
立即学习“go语言免费学习笔记（深入）”；
-
go mod init myproject后生成的go.mod中module路径写成本地路径（如file:///home/user/myproject），这是误用了绝对路径，应改为合法导入路径，例如github.com/yourname/myproject或纯域名格式example.com/myproject - 项目目录名含空格或中文，某些旧版 Go 工具链会解析失败，建议全英文、无空格、小写字母命名
- 父目录已有
go.mod，而你又在子目录里执行go mod init，Go 会拒绝覆盖嵌套模块，此时应 cd 到正确根目录再操作
为什么 go run main.go 能跑通，但 go build 出来的二进制却找不到依赖？
这不是依赖缺失，而是 Go 的构建模式差异导致的错觉：go run 自动处理模块加载和临时编译，而 go build 默认生成静态链接二进制（不依赖外部 .so 或 .dll），但它对 cgo 有特殊要求。
典型表现：程序含数据库驱动（如 github.com/mattn/go-sqlite3）、图像处理（golang.org/x/image）等需 cgo 的包，go build 失败并提示 undefined reference 或 exec: "gcc": executable file not found。
- 先确认是否启用了 cgo：
CGO_ENABLED=1 go build（Linux/macOS）或set CGO_ENABLED=1 && go build（Windows） - 确保系统已安装 GCC（macOS 安装 Xcode Command Line Tools，Ubuntu 执行
sudo apt install build-essential） - 如果目标是纯静态二进制（比如容器部署），可尝试
CGO_ENABLED=0 go build -ldflags="-s -w"，但前提是所有依赖都不依赖 cgo ——sqlite3、net包部分 DNS 解析逻辑等会失效
VS Code 里 gopls 一直卡在 “Starting”？优先检查 go env -w 写入的配置
gopls 启动失败最常见的原因是 GOPATH 或 GOPROXY 配置被手动改错，尤其当你用 go env -w GOPROXY=direct 关闭代理后，又没配好私有模块仓库，会导致 gopls 在后台反复尝试拉取失败模块，最终卡死。
实操排查顺序：
- 运行
go env GOPROXY，确认值不是空或非法地址；国内推荐设为https://proxy.golang.org,direct或清华镜像https://mirrors.tuna.tsinghua.edu.cn/goproxy/ - 检查
go env GOMODCACHE路径是否存在且可读写；若路径含空格或权限受限（如 macOS 的~/Library/Caches权限异常），gopls 可能静默失败 - VS Code 设置中关闭 “Go: Use Language Server” 再打开，强制重启 gopls；不要依赖自动重连，它有时不会真正退出旧进程
模块缓存损坏、go.sum 校验失败、IDE 缓存残留，这些都比“重装插件”更常是根源。每次改完 go env，记得在终端新开一个 tab 再验证，否则 shell 环境变量可能没刷新。
