根本原因是PATH未正确配置或未生效：Windows需重启终端或刷新环境变量，macOS/Linux要确认shell配置文件（如~/.zshrc）已添加export PATH=$PATH:$GOROOT/bin并执行source，统信UOS等系统还需手动设置GOROOT。
go version 报 command not found 怎么办
根本不是 Go 没装好，而是 PATH 没生效。Windows 用户常忽略「重启终端」或「手动刷新环境变量」；macOS/Linux 用户容易写错 shell 配置文件（~/.zshrc vs ~/.bash_profile），或漏掉 source 步骤。
- Windows：用 PowerShell 运行
Get-Command go，失败则去「系统属性 → 高级 → 环境变量」确认C:\Program Files\Go\bin（或你实际安装路径）已加入「系统变量」或「用户变量」的PATH - macOS/Linux：先运行
which go，无输出就检查GOROOT路径是否正确（如/usr/local/go或/usr/local/opt/go/libexec），再确认export PATH=$PATH:$GOROOT/bin已写入对应 shell 配置，并执行source ~/.zshrc（M1/M2 默认 zsh） - 统信 UOS 等国产系统：APT 安装后可能未自动配置
GOROOT，需手动运行go env GOROOT查看是否为空，为空则补设export GOROOT=/usr/lib/go（路径依实际安装位置而定）
go mod init 失败或依赖拉不下来
90% 是代理没设对，或者模块模式被意外关闭。Go 1.16+ 默认启用模块，但 CI 脚本、旧终端会话或某些 IDE 插件仍可能保留 GO111MODULE=off。
- 强制启用模块：
go env -w GO111MODULE=on - 设置国内代理（必做）：
go env -w GOPROXY=https://goproxy.cn,direct（goproxy.cn稳定、覆盖全，比proxy.golang.org可靠得多） - 验证代理是否生效：
go env GOPROXY输出应为https://goproxy.cn,direct；若仍是空或https://proxy.golang.org，说明上一步没成功 - 遇到
module github.com/xxx: reading https://goproxy.cn/xxx/@v/list: 404 Not Found：多数是包名拼写错误，或该包未在 goproxy.cn 缓存中——可临时加,https://goproxy.io,direct备用源，但优先排查包名是否准确
VS Code 中 gopls 启动失败或无提示
gopls 不是插件装完就跑，它依赖三个硬条件：终端里 go 命令可用、项目根目录有 go.mod、且当前文件是 .go 后缀。缺一不可。
- 打开 VS Code 终端，执行
go version和go env GOPROXY，确保两者都返回正常结果 - 确认项目根目录下存在
go.mod；没有就运行go mod init example.com/myapp（模块名随便起，但不能含空格或大写字母） - 不要把
.go文件放在$GOPATH/src下启动项目——这是旧模式路径，gopls会拒绝服务；直接在任意空目录新建项目即可 - 如果
gopls日志报"no module found"，八成是 VS Code 当前打开的是单个.go文件而非整个文件夹，右键文件 → “Reopen with Folder” 或直接用code .打开项目根目录
多版本 Go 共存时如何切换
官方不提供 go switch，但不用装第三方工具也能干净切换，关键是别动 GOROOT，靠 PATH 顺序控制优先级。
立即学习“go语言免费学习笔记（深入）”；
- 把不同版本解压到不同目录，例如：
/opt/go1.21、/opt/go1.22 - 在 shell 配置中，用函数封装切换逻辑：
alias go121='export PATH="/opt/go1.21/bin:$PATH"'
alias go122='export PATH="/opt/go1.22/bin:$PATH"'
- 每次切换后，立即运行
go version验证，同时检查go env GOROOT是否同步更新（它会自动读取PATH中第一个go所在目录） - 注意：VS Code 的 Go 插件默认读取系统
PATH，所以切完版本后要重启 VS Code 窗口，否则gopls仍可能用旧版本
-n 新窗口）、终端 shell 类型（zsh/bash）、以及 go env -w 写入的是用户级还是系统级配置。这些细节不一致，就会导致「本地能跑，IDE 报错，CI 失败」的三重割裂。 
