最常见原因是未在go.work所在根目录执行命令，Go工具链仅在此目录识别工作区，进入子目录即退化为单模块模式，导致“module xxx is not in main module”错误；须确保当前目录含go.work、所有命令统一在此执行、use路径为相对路径、删除子模块go.mod中replace、IDE正确加载工作区并匹配GOFLAGS=-mod=mod。
go.work 文件必须在根目录创建并执行命令
联合调试失败最常见原因：你在 ./cmd/app 或 ./internal/lib 里直接运行 go run 或点击 GoLand 的 ▶ 按钮。Go 工具链只在当前工作目录扫描 go.work，一旦不在该文件所在目录，它就自动退化为单模块模式，报错 module xxx is not in main module。
实操要点：
- 先执行
ls go.work确认当前终端路径下存在该文件 - 所有命令（
go build、go test、go run）必须在go.work所在目录执行 - 路径一律用相对形式，例如：
go run ./cmd/api，不能写cd ./cmd/api && go run . -
go work use的参数必须是相对于工作区根的路径，如./api，不能是../other/api或绝对路径
GoLand 必须把 go.work 目录设为 Module Root
IDE 显示 “no module found”、跳转失效、补全空白，不是 gopls 坏了，而是它压根没加载 go.work —— 因为你打开的是整个仓库顶层文件夹，或启用了 Multi-root Workspace 但没关掉自动识别。
正确做法：
- VS Code：用 File → Add Folder to Workspace… 逐个添加
./main、./lib等子模块目录；再在设置中加"go.toolsEnvVars": { "GOFLAGS": "-mod=mod" } - GoLand：右键点击含
go.work的目录 → Mark Directory as → Go Module Root - 务必关闭 Auto-add modules on open（Settings > Go > Modules），否则每个子目录被单独初始化，绕过
go.work - 验证方式：打开命令面板 → Go: Toggle Logs，确认
gopls启动时工作目录确实是go.work所在路径
调试配置里的 Working directory 不能填子目录
GoLand 调试器连不上、提示 cannot find package 或测试按钮灰色，大概率是运行配置里 Working directory 填成了 ./cmd/app 这类子路径。调试器会按该路径解析模块依赖，结果找不到其他被 go.work 引用的本地模块。
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
必须改成：
-
Working directory设为go.work所在的根目录（即含go.work文件的那层） - 在
Run kind中选 Directory，然后填./cmd/app（这是要构建的目标路径，不是工作目录） - 如果项目用了
//go:build integration这类构建标签，记得在运行配置的Tags输入框里填上空格分隔的标签名，不是逗号
go.mod 里的 replace 语句要删干净
工作区模式下，各子模块 go.mod 中的 replace 语句会被忽略，反而干扰本地修改同步 —— 比如你改了 ./lib 里的代码，但主模块仍从 replace 指向的旧 commit 加载，导致调试看到的不是最新逻辑。
清理原则：
- 所有子模块的
go.mod中，删掉形如replace github.com/xxx => ./lib的行 - 确保
go.work已通过go work use ./lib正确引用该模块 - 删完后执行
go mod tidy（在go.work根目录下），让依赖图重新收敛
最容易被忽略的是：GOROOT 必须随项目声明的 Go 版本实时变化，而不是 IDE 设置里写死的一个路径；只要 go env GOROOT 指向的不是当前 go.mod 声明版本对应的二进制，调试就可能静默失败。
