go.mod的module行必须与远程仓库地址完全一致：如仓库为github.com/yourname/api-server，则module必须声明为该路径，否则引发checksum mismatch、CI失败、IDE解析异常等问题。
go.mod 的 module 行必须匹配远程仓库地址
本地项目路径和 go.mod 里的 module 值不一致，是依赖路径错乱的根源。比如你把代码 clone 到 D:\projects\myapi，但远程仓库地址是 github.com/yourname/api-server，那 go.mod 第一行就必须写成：module github.com/yourname/api-server。写成 module myapi 或 module ./myapi 都会导致后续所有环节出问题。
常见后果包括：go get 报 checksum mismatch、CI 构建失败但本地能过、GoLand 显示 Unresolved reference 却又允许跳转——这些都不是 IDE 本身的问题，而是 Go 工具链在校验时发现路径和模块名对不上。
多模块项目中 replace 路径只能用相对路径
当你在主模块里通过 replace 指向本地子模块（比如工具库），路径必须相对于当前 go.mod 所在目录，且目标目录必须含有效的 go.mod 文件。
-
replace github.com/yourname/utils => ../utils✅ 正确：路径相对，目标有go.mod -
replace github.com/yourname/utils => /home/user/projects/utils❌ 错误：绝对路径不被支持 -
replace github.com/yourname/utils => ~/projects/utils❌ 错误：~展开由 shell 处理，Go 不识别 -
replace github.com/yourname/utils => ../utils但../utils/go.mod不存在 ❌ 会退化到 legacy mode，依赖解析不可控
replace 只影响当前模块构建，不会出现在 go list -m all 的下游依赖树中，也不会被 go mod vendor 收录——这点常被忽略，导致上线时行为不一致。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
GOPROXY 和 GOSUMDB 必须在 GoLand 内显式配置
GoLand 底部 Terminal 中执行 go env GOPROXY 和 go env GOSUMDB，如果返回空或仍是默认值 https://proxy.golang.org，说明 IDE 没生效。不能只依赖系统环境变量。
正确做法是：
File → Settings → Go → Go Modules，在 Environment 栏填入：GOPROXY=https://goproxy.cn,directGOSUMDB=gosum.io+ce6e75650+AY5qEHUk/qmHc5btzW45JVoENfazw8LielDsaI+lEbq6
勾选 Enable Go Modules integration 和 Enable for current project。
国内环境下漏配 GOSUMDB 会导致 go mod download 卡住或校验失败，而 IDE 往往只在后台日志里报错，界面无提示。
go.work 工作区下子模块的依赖路径需手动同步
用 go work init 创建工作区后，GoLand 默认只识别 go.work 所在目录为项目根。每个子模块若含独立 go.mod 和 replace，IDE 可能无法自动解析其依赖关系。
解决方法：
- 确保
go.work在顶层目录，且用该目录打开整个项目（不是某个子模块） - 检查 Settings → Go → Modules 中是否启用
Enable Go modules support，并设为Auto-sync - 子模块的
go.mod修改后，手动触发File → Reload project或点击右上角Load project按钮 - 运行配置中的
Directory必须指向含main函数的模块目录，不能只填 workspace 根路径
最易被忽略的是：子模块里写的 replace，对其他模块完全不可见；每个模块的依赖路径都是隔离的，没有“全局 replace”这回事。
