go mod tidy 报 unknown revision 或 module not found 是上游包更名后的典型症状，因 go.mod 仍引用旧路径（如 github.com/oldorg/lib），而 go 工具链无法定位其有效 commit；需确认迁移状态、清理 go.sum 残留、用 replace 重定向并指定版本号（如 v1.2.3 或 commit hash），同时同步更新 go_private 和 goproxy 配置，并精准清理缓存而非盲目执行 go clean -modcache。
go mod tidy 报 unknown revision 或 module not found
这是上游包更名后最典型的症状：你的 go.mod 里还写着旧路径，比如 github.com/oldorg/lib，但人家已迁移到 github.com/neworg/lib，Go 工具链找不到旧路径对应的有效 commit，就卡在 unknown revision。它不会自动跳转，也不会提示“该包已迁移”，只会静默失败或报错。
- 先确认是否真被更名：访问原仓库 URL，看是否有重定向、README 顶部的迁移说明，或 GitHub/GitLab 的「moved」提示
- 检查
go.sum中残留的旧路径哈希条目——它们会干扰解析，删掉再试不是万能解法，但常是必要前置动作 - 别急着全局替换
go.mod里的 import 路径；先用go list -m all | grep oldorg找出所有间接依赖中仍引用旧路径的模块
replace 语句必须写在正确位置且带版本号
replace 是绕过更名断链最直接的手段，但它只对当前模块生效，且必须出现在 go.mod 的 require 块之后、//indirect 注释之前。漏掉版本号或路径错误，Go 会忽略这条规则。
- 写法必须是：
replace github.com/oldorg/lib => github.com/neworg/lib v1.2.3（末尾的版本号不能省，否则 Go 不知道该取哪个 commit） - 如果新包尚未打 tag，可用 commit hash：
replace github.com/oldorg/lib => github.com/neworg/lib v0.0.0-20240101000000-abcdef123456 - 执行
go mod tidy后，检查go.mod是否把require github.com/oldorg/lib留着没删——它应该被自动移除，否则说明replace没生效
私有仓库更名时 GO_PRIVATE 和 GOPROXY 要同步调整
上游是公司内私有 Git 服务（如 GitLab）时，更名后光改 replace 不够。Go 默认仍会尝试走 GOPROXY 查找旧域名，而认证失败或 404 会导致整个依赖树中断。
- 确保
GO_PRIVATE包含新域名：export GO_PRIVATE="gitlab.example.com/*"（旧域名要从列表里删掉） - 若用自建 proxy，更新其配置中的仓库映射规则；若直连，确认
GOPROXY=direct并配好~/.netrc或 git credential helper - 运行
go env -w GOPROXY=direct临时关闭 proxy 调试，避免缓存干扰
go clean -modcache 不能替代精准清理
很多人第一反应是 go clean -modcache，但它清的是整个模块缓存，包括你项目无关的几十个依赖，下次 go mod tidy 又得全量下载。更麻烦的是，它不清理 go.sum 里指向旧路径的校验和，这些残留条目仍会触发校验失败。
- 优先做精准清理：
rm -f go.sum && go mod tidy（重建校验和），再手动删$GOPATH/pkg/mod/cache/download/github.com/oldorg目录 - 如果项目用 vendor，记得
go mod vendor后重新git add vendor/，否则旧路径的源码可能还躺在 vendor 里 - CI 流水线里禁用
go clean -modcache，改用go mod download+go mod verify组合，既快又可控
replace，而是旧路径可能藏在七八层间接依赖里，且不同模块对同一上游包的引用版本不一致——这时候 MVS（最小版本选择）机制反而会放大冲突。动手前，先跑一遍 go list -m all，盯着输出里那些带 // indirect 标记的旧路径，一个一个揪出来处理。
