GoLand识别go.work失败需手动启用多模块工作区：关闭项目后重新打开go.work所在根目录并确认提示，右下角显示“Multi-module workspace”且SDK版本与.tool-versions一致，否则跨模块import标红。
GoLand 识别 go.work 文件失败导致模块引用标红
GoLand 默认不自动启用多模块工作区支持，即使项目根目录存在 go.work，它仍可能按单模块逻辑解析依赖，结果是跨模块 import（如 import "github.com/org/shared"）全标红，gopls 报 “no required module provides package”。这不是代码问题，而是 IDE 没进工作区上下文。
必须手动触发工作区加载：
- 关闭当前项目（File → Close Project），再用 File → Open… 重新打开 go.work 所在的根目录（不是某个子模块目录）
- 首次打开时弹出提示 “This directory contains a go.work file. Would you like to open it as a multi-module workspace?” —— 必须点 Yes
- 若已打开但没选 Yes，删掉项目根目录下的
.idea文件夹 +go.work临时重命名，重启 GoLand 后重开根目录 - 验证：右下角状态栏应显示 “Multi-module workspace (x modules)”，且 Project 视图里展开后能看到多个模块节点
GOROOT 和 SDK 配置必须与 .tool-versions 中的 Go 版本一致
GoLand 的 SDK 设置和终端实际生效的 Go 版本不一致，是跨模块调试失败的最常见原因。比如 .tool-versions 写着 golang 1.22.3，但 GoLand 的 Settings → Go → GOROOT 指向的是系统默认的 /usr/local/go（通常是 1.21.x），会导致 go run 成功但断点不命中、go list -m all 输出缺失模块。
正确做法：
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 进入 Settings → Go → GOROOT，点击右侧文件夹图标，选择
asdf安装路径下的对应版本（macOS/Linux 通常是~/.asdf/installs/golang/1.22.3，Windows 是C:\Users\XXX\.asdf\installs\golang\1.22.3） - 确认该路径下有
src、pkg、bin三个文件夹，bin/go可执行 - 点 Apply → 关闭并重启 GoLand（仅 Reload project 不生效）
- 打开 Terminal 面板，执行
which go和go version，输出应与asdf current golang完全一致
VS Code 插件级 asdf 集成缺失，gopls 仍用旧 Go 版本
即使终端和 GoLand 都对齐了版本，VS Code 的 gopls 仍可能卡在系统默认 Go 上，表现为跳转失效、补全错乱、go.work 中声明的模块不被识别。这是因为 VS Code 默认不读取 .tool-versions，gopls 启动时直接调用 PATH 里的第一个 go。
必须安装并启用官方插件：
- 安装扩展：
asdf（by asdf-community）或Shell Command: Install 'code' command in PATH（确保 shell 集成可用） - 在 VS Code 设置中搜索
terminal integrated env，勾选 “Run code in terminal” 并确保 shell 配置加载了 asdf（如source ~/.asdf/asdf.sh） - 打开命令面板（Ctrl+Shift+P），运行 “Developer: Restart Language Server”，强制
gopls重建会话 - 验证：打开任意
.go文件，底部状态栏应显示 Go 版本号（如 “Go 1.22.3”），且go env GOROOT输出与终端一致
CI 构建时 go.work 被误用引发 no required module 错误
go.work 是开发期机制，CI 流水线必须显式禁用它，否则 go build 会尝试加载工作区所有模块，而 CI 环境通常只 checkout 单个子模块，导致 no required module provides package。
构建命令必须加 -modfile=go.mod：
- CI 脚本中不要用
go build ./...，而要用go build -modfile=go.mod -o bin/app ./cmd/app - 如果使用 Makefile，定义目标时显式传参：
build: export GOFLAGS := -modfile=go.mod - Docker 构建中，在
WORKDIR后加RUN go env -w GOWORK=彻底清空工作区上下文 - 本地验证：临时重命名
go.work为go.work.bak，运行go build应与 CI 行为一致
go.work 形同虚设。最容易被忽略的是 VS Code 的 gopls 重启和 CI 的 -modfile 显式指定，这两处不处理，其他配置全白搭。 
