goland模块依赖路径配错90%源于go.mod的module行与实际仓库地址不一致：module必须严格匹配远程git路径（如github.com/yourname/api-server），否则导致checksum mismatch、ci失败、ide提示“unresolved reference”等；replace路径须为相对路径且目标含go.mod；goproxy和gosumdb需在goland设置中显式配置，不可仅依赖系统变量。
GoLand 里模块依赖路径配错，90% 是因为没搞清 go.mod 的 module 行和实际仓库路径必须严格一致，而不是 IDE 设置的问题。
go.mod 中的 module 指令必须匹配远程仓库地址
你 push 到 GitHub 的地址是 github.com/yourname/api-server，那 go.mod 第一行就必须是：module github.com/yourname/api-server。哪怕本地只是临时建个文件夹叫 myapi，也不能写成 module myapi。
常见错误现象：
- 别人
go get github.com/yourname/api-server@v0.2.0后报verifying github.com/yourname/api-server@v0.2.0: checksum mismatch - CI 构建失败，但本地
go build成功 - GoLand 提示 “Unresolved reference” 却又不报错，import 能跳转但无法补全
根本原因：Go 工具链用 module 值生成校验路径，跟实际 Git 地址不一致时，go.sum 校验直接失败。IDE 只是把底层错误“安静地”藏在了后台日志里。
本地调试多模块项目时，replace 路径必须相对当前 go.mod
比如主模块在 ./service，依赖的工具库在 ../utils，那 service/go.mod 末尾要加：
replace github.com/yourname/utils => ../utils
注意三点：
-
../utils必须包含有效的go.mod（哪怕只是module github.com/yourname/utils）；否则 Go 会 fallback 到 legacy mode，可能漏掉依赖或版本混乱 - 路径不能写成
~/projects/utils或C:\dev\utils——replace不支持绝对路径或用户主目录缩写 -
replace只影响当前模块构建，不会出现在go list -m all的下游依赖树中，也不会被go mod vendor收录
GoLand 自动下载依赖失败，大概率是 GOPROXY 或 GOSUMDB 没生效
GoLand 底部 Terminal 执行 go env GOPROXY 和 go env GOSUMDB，确认值不是空或默认的 https://proxy.golang.org。国内常用配置是：
GOPROXY=https://goproxy.cn,direct<br>GOSUMDB=gosum.io+ce6e75650+AY5qEHUk/qmHc5btzW45JVoENfazw8LielDsaI+lEbq6
关键细节：
- GoLand 的 Settings → Go → Go Modules 里的
Environment字段，必须显式填上GOPROXY=...，不能只依赖系统环境变量（尤其 Windows PowerShell 和 CMD 环境变量不互通） -
GOSUMDB值带签名密钥，不能简写成gosum.io，否则校验失败，go mod tidy会卡住或报failed to verify module - 如果公司有私有代理，
direct必须保留在GOPROXY最后，否则私有模块无法回源
依赖路径在代码里写错，GoLand 不会帮你自动修正
假设你把 github.com/yourname/utils 的 module 写成了 github.com/yourname/common-utils，那所有 import 语句也得跟着改 —— import "github.com/yourname/common-utils"。GoLand 的 import 补全、跳转、重命名都基于这个字符串，它不会“猜”你本意想用哪个路径。
容易忽略的点：
- 重构模块名后，必须全局搜索替换所有
import语句，不能只改go.mod - Git 子模块或 symlink 目录下初始化的模块，
module名仍要按最终公开 URL 写，而不是文件系统路径 -
go mod edit -replace命令生成的replace行，路径分隔符在 Windows 上要用/（Go 工具链统一处理），别手误写成\
模块路径不是命名自由发挥的地方，它是 Go 生态里唯一能靠得住的“身份证”。配错一次，后续所有协作、CI、发布都会反复踩坑，而且错误信息往往藏得很深。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
