go mod init 必须在项目根目录执行，否则会在子目录创建独立模块，导致 import 失败、go list 扫描不到子包；正确做法是仅在根目录运行 go mod init github.com/yourname/project，误生成的子目录 go.mod 应删除并用 go mod tidy 重建依赖。
go mod init 在子目录执行会创建独立模块
在 GoLand 里右键新建文件夹后直接写 main.go 并运行，IDE 可能自动帮你生成 go.mod —— 这是危险信号。只要你在非项目根目录下触发 go mod init，Go 就会认为这是一个全新模块，和外层模块完全隔离。
常见错误现象：import 同仓库下的其他子包失败，报错 cannot find module providing package；或者 go list ./... 扫不到子目录里的包。
- 正确做法：所有
go mod init命令只在项目最外层根目录执行一次，例如go mod init github.com/yourname/project - 如果误操作已生成多个
go.mod，删掉子目录里的go.mod，然后用go mod tidy在根目录重建依赖关系 - 子目录代码想被外部引用，必须确保它属于根模块路径的一部分（比如
github.com/yourname/project/api），而非独立域名
多模块工作区需显式声明 go.work
当你真需要多个互不隶属的模块共存（比如同时开发 cli、api、shared 三个可单独发布的组件），就得用 go.work 文件，而不是靠 IDE 自动识别。
GoLand 不会自动生成或管理 go.work，你得手动创建：
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 在项目根目录下运行
go work init - 再逐个添加模块路径：
go work use ./cli ./api ./shared -
go.work文件内容类似：go 1.22<br><br>use (<br> ./cli<br> ./api<br> ./shared<br>)
- 此时 IDE 才能跨模块跳转、补全、调试；否则它只认当前打开的
go.mod所在模块
.idea 目录和 .gitignore 必须同步处理
GoLand 默认把项目配置存在 .idea 目录里，但这个目录含大量本地路径、缓存、用户偏好——一旦提交到 Git，别人 clone 下来立刻报错或无法加载项目。
容易踩的坑：.gitignore 里漏写 .idea/，或者写成了 .idea（少斜杠），导致部分子目录被意外追踪；更糟的是，有人曾 git add -f .idea 强制提交过，后续再 git rm -r --cached .idea 也难彻底清理干净。
- 确认
.gitignore第一行是.idea/（结尾带斜杠） - 如果已误提交，先删本地
.idea，再执行git rm -r --cached .idea，最后git commit -m "remove .idea from tracking" - 多模块项目里，每个子模块不需要单独的
.idea—— 整个项目共享一个，放在根目录即可
GoLand 的 SDK 和模块绑定不是自动的
新建项目时选了 Go SDK 版本，不代表所有子模块都用同一版本。尤其当你在不同目录下分别执行 go mod init，GoLand 可能为每个模块单独配置 SDK，结果编译时出现 go: inconsistent versions。
真实场景：根模块用 Go 1.22，子模块用了 1.21，go build 成功但 go test 报错，因为测试框架依赖新版语法。
- 统一 SDK：在
Settings | Go | GOROOT里指定唯一 SDK 路径，不要勾选 “Auto-detect” - 检查每个模块的
go.mod头部go 1.xx版本号是否一致 - 运行
go version和go env GOROOT确认终端环境与 IDE 一致，避免 IDE 内置终端和系统终端行为不一致
go.work，什么时候该拆成独立仓库。IDE 只负责识别已存在的结构，不会替你做架构决策。 
