go mod init 必须在项目最外层文件夹执行，vscode仅识别当前打开目录是否含go.mod；若在子目录初始化，gopls会忽略go.mod并退化为gopath模式，导致补全、跳转等功能失效。
go mod init 必须在项目根目录执行
VSCode 不会自动识别“哪个文件夹是模块根”，它只看当前打开的文件夹里有没有 go.mod。如果你在子目录里执行 go mod init，生成的 go.mod 会被 gopls 当作孤立文件忽略，导致“找不到包”“跳转失败”。
- 正确做法：用 VSCode 打开**整个项目最外层文件夹**（比如
myapp/），确保该目录下没有嵌套的go.mod - 错误做法：打开
myapp/cmd/server/这类子路径再初始化——gopls 会退化为 GOPATH 模式，补全和 hover 全失效 - 验证方式：终端进入该文件夹后运行
go list -m，应输出模块名；若报错no modules found，说明路径不对
GO111MODULE=on 是硬性前提，不是可选项
即使 Go 1.16+ 默认开启，VSCode 的 Go 扩展（尤其是 gopls）仍可能读取旧环境变量或工作区配置覆盖它。一旦关闭，所有依赖解析都会 fallback 到 GOPATH，go.mod 形同虚设。
- 检查命令：
go env GO111MODULE输出必须是on，不是auto或off - Windows 用户注意：
setx GO111MODULE on只对新终端生效，旧终端要手动set GO111MODULE=on - VSCode 工作区级兜底：
.vscode/settings.json中加"go.toolsEnvVars": {"GO111MODULE": "on"}，避免被全局设置干扰
GOPROXY 必须带 direct 后缀，否则私有模块 404
国内镜像（如 https://goproxy.cn）不代理公司内网 GitLab/GitHub 私有库，如果 GOPROXY 没配 direct，go get internal/pkg 会直接 404，而不是回退到直连。
- 正确值：
https://goproxy.cn,direct（逗号分隔，无空格） - 错误值：
https://goproxy.cn（缺direct）、https://goproxy.cn;direct（分号错）、"https://goproxy.cn,direct"（引号进环境变量是非法的） - 验证方法：
go env GOPROXY输出应与设置完全一致；改完后务必重启gopls（Ctrl+Shift+P →Go: Restart Language Server）
GOROOT 和 GOPATH 不影响 Modules 路径，但影响工具链调用
Modules 模式下，go build、go test 完全不依赖 GOPATH，但 VSCode 插件启动 gopls、dlv 等工具时，会从 $GOPATH/bin 或 $GOROOT/bin 查找二进制。路径错会导致“command not found”或调试器无法启动。
-
GOROOT必须指向 Go 安装根目录（如C:\Program Files\Go或/usr/local/go），不能是子目录 -
GOBIN不必设——只要$GOPATH/bin在系统PATH里，插件就能找到gopls - 常见症状：
Go: Install/Update Tools显示部分工具“failed to install”，大概率是PATH没包含$GOPATH/bin
gopls 能否定位模块、能否加载私有依赖、能否调起调试器。任何一个环节断在路径上，VSCode 就只剩语法高亮。
