VSCode需安装官方Go扩展（golang.go）、启用GO111MODULE=on、项目根目录含go.mod，并正确配置launch.json的program路径及env环境变量，缺一将导致提示/调试/格式化等功能异常。
VSCode 本身不内置 Go 支持，必须通过 Go 扩展 + 正确的工具链路径 + 合理的 settings.json 配置才能正常运行调试、跳转、格式化等功能；缺任一环都可能表现为“代码没提示”“F5 调试报错”或“go mod 不生效”。
装对扩展：只用官方 Go 扩展，禁用其他 Go 相关插件
VSCode 市场里有多个名字含 “Go” 的扩展（如 Go Tools、golang-go），但唯一受维护且与 gopls 深度集成的是由 golang 官方发布的 Go 扩展（ID：golang.go）。安装后它会自动下载 gopls、dlv、goimports 等二进制工具（除非禁用自动安装）。
- 卸载所有非
golang.go的 Go 插件，否则可能冲突导致gopls启动失败或诊断重复 - 检查扩展设置里
go.toolsManagement.autoUpdate是否为true（推荐），避免手动维护工具版本 - 若公司内网无法访问
golang.org，需提前在终端执行：GO111MODULE=on GOPROXY=https://goproxy.cn go install golang.org/x/tools/gopls@latest
，再在 VSCode 设置中指定go.goplsPath指向本地可执行文件
go 和 GOPATH 不再决定一切：优先启用 GO111MODULE=on
Go 1.16+ 默认开启模块模式，GOPATH 对开发体验影响已大幅降低。VSCode 的 Go 扩展默认按模块方式解析项目，但若打开的文件不在 go.mod 目录下，或 go env -w GO111MODULE=off 曾被误设，就会退回到旧式 GOPATH 模式，导致依赖无法识别、go.sum 不更新、go run 报 no required module provides package。
- 确认当前终端和 VSCode 终端中
go env GO111MODULE输出为on - 项目根目录必须含
go.mod；若没有，用go mod init myproject初始化（注意包名不要用main以外的字面量起始，否则go run可能静默失败） -
go.gopath设置项在模块模式下基本无效，不必配置；若强行设了错误路径，反而会让gopls在错误位置查找依赖
调试配置别硬套模板：重点改 program 和 env
VSCode 自动生成的 .vscode/launch.json 中的 program 字段常写成 "${workspaceFolder}"，这仅在单 main.go 文件时有效；实际项目多含子目录，必须指向具体可执行入口（如 "${workspaceFolder}/cmd/myapp/main.go"），否则调试启动时报 could not launch process: fork/exec ...: no such file or directory。
立即学习“go语言免费学习笔记（深入）”；
-
program必须是.go文件路径，不能是目录或二进制名（VSCode 会自动编译） - 若程序依赖环境变量（如
CONFIG_PATH或DB_URL），在env字段中显式声明，不要依赖终端已有变量（调试进程不继承 shell 环境） - Windows 下路径分隔符用
/即可（VSCode 内部统一处理），但env中的PATH若需追加，仍要用;分隔
常见症状与速查点
遇到“跳转失效”“保存不格式化”“悬停没类型信息”，先验证三个基础项是否就位：
-
gopls进程是否在运行？任务管理器或ps aux | grep gopls查看；若无，检查go env GOCACHE路径是否有写权限 -
go fmt是否可用？在 VSCode 集成终端执行go fmt ./...，失败则说明GOROOT或PATH配置异常 - 打开的文件是否属于当前
go.mod模块？右下角状态栏应显示模块名（如myproject (go1.21.0)），若显示No module，说明工作区根选错了
真正卡住的地方往往不是配置项本身，而是 gopls 加载模块时静默失败——它不会弹窗报错，只让功能逐步失灵。此时打开命令面板（Ctrl+Shift+P），运行 Go: Toggle Verbose Logging，再重启语言服务器，日志里通常会暴露 failed to load packages 或 proxy 访问超时这类线索。
