gopls 必须识别为模块项目才能启用 auto-import，即工作区根目录需含 go.mod 文件且通过 go list -m 验证，同时 settings.json 中必须启用 go.gopls.experimental.workspaceModule 等关键配置，并通过 Cmd+/Ctrl+. 手动触发 Add import。
gopls 必须识别为模块项目才能启用 auto-import
VSCode 的 Go 自动导入不靠编辑器本身，而是由 gopls 语言服务器提供支持，但它只在“模块模式”下工作。如果你打开的是单个 .go 文件，或工作区根目录不含 go.mod，gopls 就会退化为“无模块模式”，直接禁用所有 import 相关代码操作。
验证方式：终端进入当前工作区根目录，运行 go list -m。成功输出模块路径（如 module github.com/you/project）才算通过；若报 not in a module，说明没识别上。
- 必须用
File → Open Folder打开go.mod所在目录，不能只打开子文件夹或单文件 - 多根工作区（Multi-root Workspace）中，确保主模块的
go.mod在第一个根目录里，否则gopls无法确定上下文 - 如果项目用了
vendor/，需手动加配置："gopls": {"build.experimentalUseVendor": true}
settings.json 中关键配置项不能遗漏
即使项目结构正确，VSCode 设置里几个布尔值没开，gopls 也不会暴露 Add import 选项。尤其注意 go.gopls.experimental.workspaceModule —— 这是 Go 1.21+ 强制要求的开关，旧版设置名（如 go.gopls.usePlaceholders）已失效。
推荐最小有效配置（粘贴进 settings.json）：
立即学习“go语言免费学习笔记（深入）”；
{
"go.useLanguageServer": true,
"go.gopls.experimental.workspaceModule": true,
"go.toolsManagement.autoUpdate": true,
"go.gopath": "",
"editor.codeActionsOnSave": {
"source.organizeImports": false
}
}
-
"source.organizeImports": false是故意关掉的——自动整理 imports 容易误删手动写的分组或注释，应只用手动触发 -
"go.gopath": ""必须清空，否则gopls可能降级到 GOPATH 模式，绕过模块逻辑 - 不要设
"go.autocompleteUnimportedPackages": true，它只影响补全列表显示，和自动导包无关，还可能干扰gopls行为
触发方式不是保存，而是 Cmd+. + 手动选 “Add import”
很多人卡在这一步：敲完 json.Marshal，保存文件，发现没加 import "encoding/json"。这是因为自动导包从不“静默发生”，它必须由用户显式调用 Quick Fix。
- 光标停在未定义标识符上（如
http.HandleFunc的http或整个词） - 按
Cmd+.（macOS）或Ctrl+.（Windows/Linux）唤出菜单 - 从列表中选择明确带
Add import "net/http"字样的项（不是Import package或其他模糊描述） - 如果没看到该选项，先运行
go list -json net/http确认包可解析；失败则检查GOROOT是否污染了模块查找路径
刚加依赖后没反应？先跑 go mod tidy
gopls 不监听 go.mod 文件变化，它只在启动或收到文件变更事件时重新加载模块信息。你执行 go get github.com/some/pkg 后，gopls 并不知道新包存在，除非你强制刷新缓存。
- 最可靠做法：终端执行
go mod tidy，再重启 VSCode（或用Developer: Reload Window） - 如果用了 replace 或 indirect 依赖，
go list -m all | grep pkgname能确认是否真正纳入模块图 - 长期开发建议把
go mod tidy加进 pre-commit hook，避免团队成员因缓存不同步导致 import 缺失
真正容易被忽略的是模块边界与缓存的耦合性——gopls 的 import 行为不是“语法层面”的推断，而是基于完整模块图的符号解析。一旦模块加载失败、路径错位或缓存陈旧，它连“这个包是否存在”都回答不了，更别说帮你加 import 了。
