gopls启动失败或状态栏不显示“language server: gopls”的根本原因是gopls二进制未就位或vs code找不到它，需验证go版本≥1.21、goproxy生效、gobin配置正确、go.mod存在，并手动安装gopls后硬编码绝对路径至go.gopls.path。
gopls启动失败或状态栏不显示“Language Server: gopls”
根本原因通常是 gopls 二进制未就位，或 VS Code 找不到它——不是插件没装，而是工具链断在了 GOPROXY、GOBIN 或项目根目录上。
- 先验证
go version是否 ≥ 1.21（推荐 1.22+），否则gopls启动会静默失败 - 运行
go env -w GOPROXY=https://proxy.golang.org,direct（国内可换为https://goproxy.cn），再执行go env GOPROXY确认生效 -
go env GOBIN若为空，必须设为$GOPATH/bin；确保该路径存在、可写，且已加入PATH - 手动安装：终端执行
go install golang.org/x/tools/gopls@latest，然后用which gopls拿到路径，填入 VS Code 设置里的go.gopls.path - 打开的文件夹必须含
go.mod——gopls不支持 GOPATH 模式下的跨目录索引，否则右下角永远卡在 “Loading…”
大型项目中gopls CPU 占用高、编辑卡顿
不是配置少了，而是默认开启了太多分析器和扫描范围。大型项目（模块数 >5、代码行数 >50k）需要主动收缩能力边界。
- 禁用高频开销项：
"analyses": {"undeclaredname": false, "shadow": false}（shadow在嵌套作用域多时尤其耗时） - 关闭静态检查：
"staticcheck": false，它会触发完整依赖图遍历，极易阻塞主线程 - 限制索引范围：设
"experimentalWorkspaceModule": false，避免跨go.mod边界加载无关模块 - 降低诊断延迟：
"diagnosticsDelay": "2s"，避免每次按键都触发重分析 - 禁用 vendor 目录扫描：
"build.experimentalUseVendor": true+"build.ignoreVendor": true（如果项目不用 vendor，直接删掉该键）
补全不准、跳转失效、inlay hint 不显示
这些表象背后常是模块感知错乱或缓存污染，而非功能开关没开。
- 确认
"gopls": {"completeUnimported": true}已启用——否则未导入包的符号无法补全 - inlay hint 需要明确开启子项：
"ui.inlayhint.hints": {"assignVariableTypes": true}，只开ui.inlayhint顶层开关无效 - 跳转失败优先查
output → gopls (server)日志，若频繁出现cache.load failed，说明某依赖模块解析失败，需检查其go.mod是否合法或网络是否能拉取 - 强制刷新缓存：命令面板运行
Go: Restart Language Server，比重启 VS Code 更有效 - 避免在
vendor/目录内编辑——gopls对 vendor 的处理逻辑与 module mode 冲突，易导致符号定位偏移
VS Code 调试（dlv）启动失败或断点不命中
调试失败几乎全是路径和上下文问题，跟 gopls 配置无关，但常被误判为语言服务器故障。
-
dlv必须和gopls一样装在$GOBIN下，且 VS Code 能通过PATH访问到；单独执行dlv version验证 -
launch.json中"program"必须指向可执行入口（如"${workspaceFolder}/main.go"），不能只写"${workspaceFolder}"（除非是 module 根且含 main） - 确保当前调试的 Go 文件属于 active module——即所在目录能向上找到
go.mod，且该文件未被//go:build条件编译排除 - 禁用编译优化：
"env": {"GODEBUG": "gcstoptheworld=1"}或在go build命令加-gcflags="all=-N -l"，否则断点可能被内联或消除 - 若用远程调试或容器调试，
dlv必须与目标环境架构一致（如 arm64 容器不能用 amd64 dlv）
assignVariableTypes；多人协作项目务必把 .vscode/settings.json 提交进仓库，避免各自瞎配。最常被忽略的是 go.mod 的 clean 程度——一个坏掉的 replace 或不兼容的 require 版本，会让 gopls 在后台反复 retry，CPU 就这么烧起来了。
