Go命令不可用需检查PATH是否包含/usr/local/go/bin；VS Code补全依赖gopls，须确保其正常运行、项目含go.mod/go.work、配置正确且缓存无污染。
Go 1.21+ 安装后 go 命令不可用？检查 $PATH 和安装方式
Mac 或 Linux 下用官方 .pkg/.tar.gz 安装后，go 命令在终端报 command not found，大概率是 $PATH 没包含 /usr/local/go/bin。Homebrew 安装则默认加入 PATH，但 M1/M2 芯片 Mac 上可能装到 /opt/homebrew/bin，需确认 which go 输出。
- 手动添加：在
~/.zshrc（或~/.bash_profile）末尾加export PATH=$PATH:/usr/local/go/bin，然后source ~/.zshrc - 验证：运行
go version，应输出类似go version go1.21.6 darwin/arm64 - Windows 用户注意：安装时勾选 “Add Go to PATH”，否则需手动把
C:\Program Files\Go\bin加入系统环境变量
VS Code 中 Go 扩展无法激活补全？优先排查 gopls 状态
VS Code 的 Go 补全依赖 gopls（Go language server），不是靠本地 LSP 插件硬编码实现的。如果敲 fmt. 没弹出函数列表，或跳转定义失效，先看右下角状态栏是否显示 gopls: ready。若显示 gopls: starting... 卡住，说明服务启动失败。
- 手动触发重装：按
Cmd+Shift+P（Mac）或Ctrl+Shift+P（Win/Linux），输入Go: Install/Update Tools，勾选gopls后回车 - 检查
gopls是否可执行：终端运行which gopls，若无输出，说明没装或不在 PATH；运行go install golang.org/x/tools/gopls@latest手动安装 - 避免 GOPROXY 干扰：国内用户若设了私有代理但不可达，
gopls初始化会超时。临时清空GO111MODULE=on和GOPROXY再试
补全不生效于 vendor 目录或旧模块项目？确认 go.work 或 go.mod 存在
gopls 默认只对启用了 module 的项目提供完整补全。如果你打开的是一个没有 go.mod 的老项目，或者只是某个子目录（比如只打开了 vendor/github.com/sirupsen/logrus），补全会严重受限甚至完全关闭。
- 新建项目务必先运行
go mod init example.com/myapp生成go.mod - 多模块工作区用
go work init+go work use ./module1 ./module2生成go.work，VS Code 会自动识别 - 不要直接打开
vendor/子目录——应打开包含go.mod的根目录，否则gopls认为这是“非 module 模式”，禁用类型推导和跨包补全
补全候选项太少或类型提示错误？检查 gopls 配置与缓存
即使 gopls 启动成功，也可能因配置不当或缓存污染导致补全质量下降，例如不显示方法、参数提示错乱、结构体字段漏掉等。
- VS Code 设置中搜索
gopls，确保"go.gopls.usePlaceholders": true（启用参数占位符）和"go.gopls.completeUnimported": true（补全未导入包）已开启 - 清除缓存：关闭 VS Code，删除
$HOME/Library/Caches/gopls（Mac）、%LOCALAPPDATA%\gopls（Win）或$HOME/.cache/gopls（Linux） - 调试模式：在 VS Code 设置里加
"go.gopls.logLevel": "verbose"，重启后查看输出面板 →gopls (server)日志，常见报错如
no packages matched暗示路径解析失败
go env -w GOPROXY=https://proxy.golang.org,direct go env -w GOSUMDB=sum.golang.org
补全背后是 gopls 对整个 module 的 AST 解析和类型检查，任何环节断开（路径、代理、权限、磁盘空间）都可能导致功能降级。最常被忽略的是：以为装了 Go 就自动有补全，其实真正干活的是 gopls —— 它得能下载依赖、读取源码、构建索引，缺一不可。
