go clean -modcache 是重构后依赖失效的第一响应动作，它清空模块缓存强制重新下载校验，解决项目重命名或路径变更后 go mod tidy 无输出、不拉依赖的问题。
go clean -modcache 是重构后依赖失效的第一响应动作
项目重命名或模块路径变更后，go mod tidy 无输出、不拉依赖，不是命令坏了，而是本地缓存里还存着旧路径的元数据。Go 工具链会尝试按新 go.mod 中的模块路径去缓存里匹配，匹配不上就静默跳过——它不会报错，也不会主动清理旧缓存。
直接执行：go clean -modcache
这条命令会清空 $GOPATH/pkg/mod（或 Go 安装目录下的对应缓存路径），强制后续所有依赖重新下载、校验、解压。注意：它不删 go.sum，也不动 go.mod，只清缓存层。
- 别用
rm -rf $GOPATH/pkg/mod手动删——容易误删其他项目缓存，且可能残留锁文件 - 清完缓存后，立刻跑
go mod tidy，不要先go build，否则可能触发部分缓存回退 - 如果项目用了私有仓库，清缓存后首次
go mod tidy可能因权限失败，需确认GOPRIVATE已配置
replace 不是万能解药，但重构过渡期必须用
当旧模块路径（如 github.com/user/old-proj）已被其他依赖硬编码引用，而你已切到新路径（github.com/user/new-proj），仅靠 go clean -modcache 无法让第三方包自动识别新地址。这时得用 replace 显式接管。
在 go.mod 顶部添加：
replace github.com/user/old-proj => ./
或指向新路径：
replace github.com/user/old-proj => github.com/user/new-proj v0.0.0-00010101000000-000000000000
-
./表示本地当前目录，适合还在开发中、未打 tag 的阶段 - 用 commit hash 构造伪版本（如
v0.0.0-20260804130000-abcdef123456）比latest更稳定，避免后续go get意外升级 -
replace后必须跟go mod tidy，否则go.sum不更新，CI 构建会失败 - 别在
replace里写github.com/user/old-proj => github.com/user/new-proj而不带版本——Go 会报错 “invalid pseudo-version”
go mod graph 和 go mod why 必须配合使用
重构后出现 undefined: xxx 或 cannot load xxx: module xxx@version is not a dependency，说明某个包被间接引入但版本没对齐。单看 go.mod 很难发现谁在拉旧版。
分两步查：
先看谁在引用问题模块：
go mod graph | grep 'github.com/user/old-proj'
再查具体路径：
go mod why github.com/user/old-proj
- 输出里如果出现
main→some-dep→github.com/user/old-proj，说明是some-dep的go.mod锁死了旧路径 - 若
go mod why返回(main module does not need github.com/user/old-proj)，但go mod graph显示它存在，说明该模块是// indirect引入的“幽灵依赖”，需手动go get新版覆盖 - 注意：某些内部工具或生成代码会硬编码 import 路径，
replace无效，得改源码
重构完成后的收尾动作常被忽略
缓存清了、replace 加了、go mod tidy 跑过了，不代表万事大吉。真正容易出问题的是那些没显式声明却实际依赖旧路径的地方。
- 检查所有
import语句是否已更新为新路径——IDE 可能缓存旧导入，手动搜"old-proj"确保清零 - 运行
go list -m all | grep old-proj，确认输出为空；若有残留，说明某依赖的go.mod还没同步更新 - CI 流程里加一行
go mod verify，防止go.sum被绕过或篡改 - 如果项目用了
go.work，记得同步更新go.work文件里的use列表，否则工作区仍会加载旧模块
