goland本地包不识别主因是module路径未对齐：需确保主项目go.mod的require路径、replace左侧模块名、本地包go.mod的module声明三者完全一致，且replace右侧为含go.mod的相对路径。
GoLand 里本地包不识别，八成是 module 路径没对齐
GoLand 本身不决定包能不能导入，它只是读取 go.mod 和 Go 工具链的解析结果。如果你写 import "github.com/yourname/utils" 却标红、跳转失败、运行报 cannot find module providing package，问题几乎一定出在：主项目 go.mod 中 require 的路径，和本地模块 go.mod 第一行声明的 module 名不一致。
常见错误包括：
- 本地模块
go.mod写的是module github.com/yourname/utils/v2，但主项目require的是github.com/yourname/utils - 大小写不一致：本地是
github.com/YourName/utils，主项目写成github.com/yourname/utils - 多了一层
/v1或少了斜杠，比如github.com/yourname/utilsv1（注意没有/）
解决方法很简单：打开本地模块根目录下的 go.mod，复制第一行 module xxx 的完整字符串，粘贴到主项目 go.mod 的 require 行里，确保一字不差。
replace 指令必须用相对路径，且指向含 go.mod 的目录
replace 不是“让 Go 去找某个文件夹”，而是告诉 Go：“当我要加载这个 module 名时，请实际从这个路径读取源码”。所以路径必须满足两个硬性条件：
- 必须是相对于主项目
go.mod所在目录的路径（不是 shell 当前路径，也不是 GOPATH） - 该路径下必须存在有效的
go.mod文件（即它本身是一个合法 module）
例如主项目在 ~/myapp，本地模块在 ~/myapp/internal/utils，那么 go.mod 中应写：
replace github.com/yourname/utils => ./internal/utils
注意：./internal/utils 不能省略 ./，也不能写成 internal/utils 或 ../myapp/internal/utils。如果模块放在上层目录（如 ~/utils），就写 ../utils —— 但这种结构 CI 构建时大概率失败，不推荐。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
GoLand 索引失效？先检查 GOPROXY 和 vendor 模式
即使 go build 能跑通，GoLand 仍可能显示红色波浪线或无法跳转，原因通常是 IDE 没索引到本地替换后的代码。这时要确认两件事：
- GoLand 设置中是否启用了 Go Modules 集成（Settings → Go → Go Modules → Enable Go modules integration）
- 是否设置了
GOPROXY=direct或类似代理（Settings → Go → GOPROXY），避免 IDE 尝试从远程拉取而忽略本地replace）
另一个隐藏雷区是 vendor 模式：一旦你执行过 go mod vendor，GoLand 默认会优先从 vendor/ 加载依赖 —— 而 replace 不会把本地模块复制进去，导致 IDE 和构建行为不一致。建议开发阶段禁用 vendor，或直接删掉 vendor/ 目录再重启 IDE。
上线前必须清理 replace，CI 里留着等于埋雷
replace 是纯开发期机制，CI 环境没有你的本地路径，go mod download 会失败，或者静默 fallback 到旧版远程 tag，引发线上行为差异。最稳妥的做法不是靠人肉检查，而是加一道自动化卡点：
在 CI 脚本开头加一行：
grep -q "replace" go.mod && { echo "ERROR: go.mod contains replace, forbidden in CI"; exit 1; }
真正容易被忽略的是：即使你记得手动删 replace，如果之前运行过 go mod tidy，它可能把本地模块的伪版本（如 v0.0.0-20260804123456-abcdef123456）写进 require 行。上线前务必确认 require 行后面没有 // indirect 以外的注释，且版本号是真实 tag（如 v1.2.0），而不是伪版本。
