go mod download卡住是因隐式循环依赖导致无限递归解析，典型诱因是replace指向含反向依赖的本地模块或形成闭环，需用go list -m all和临时删go.sum排查，go mod graph辅助定位反向边。
为什么 go mod download 会卡住不动
不是网络慢，也不是代理没配——是模块图里存在隐式循环依赖，go mod 在解析 go.sum 和 go.mod 时陷入无限递归尝试，最终表现为 CPU 占用低、无错误输出、命令长时间挂起。
典型诱因：本地 replace 指向另一个尚未 clean 的模块，而该模块又通过 indirect 依赖回指当前模块；或两个模块互相 replace 形成闭环。
- 检查
go.mod中所有replace语句，确认目标路径不指向本项目子目录（如replace example.com/a => ./a），也不指向另一个正在开发、且自身含replace的模块 - 运行
go list -m all看是否报错；若卡住或输出invalid version: unknown revision，说明依赖图已断裂 - 临时删掉
go.sum再试go mod download，如果成功，说明旧go.sum里存了不一致的校验记录，需重置而非修复
如何用 go mod graph 快速定位循环边
go mod graph 输出的是有向边列表，但默认不报错也不高亮环。你需要人工过滤 + 推理，重点找「反向指向自己」的路径。
- 先执行
go mod graph | grep 'your-module-name'，看是否有行形如your-module-name@v0.0.0-00010101000000-000000000000 your-module-name@v0.0.0-00010101000000-000000000000（自环） - 更常见的是 A → B → C → A，这时用
go mod graph | awk '{print $1}' | sort | uniq -c | sort -nr | head -5找高频上游模块，再对这些模块做子图追踪 - 注意
go mod graph不显示replace后的实际路径，要结合go mod edit -json看真实依赖映射关系
替换规则（replace）写错的三个高危模式
replace 是最常引发循环的配置项，尤其在多模块联调时。它不校验目标是否存在，只做字符串替换，出错后静默失败。
-
replace example.com/m => ../m：上级目录../m的go.mod若也含replace example.com/m => .，就构成闭环 -
replace example.com/m => ./m且./m是 symlink：Go 1.21+ 默认跟随符号链接，但go mod tidy可能按真实路径解析，导致模块名和路径不匹配 - 多个
replace指向同一模块的不同本地路径（如./a和../vendor/a），Go 会尝试加载两者并比对版本，一旦两者go.mod声明的 module 名不同，就触发校验失败+重试逻辑，表现就是卡住
绕过死锁的临时调试手段
当必须继续开发又无法立刻理清依赖环时，可用隔离策略抢出时间窗口。
- 在项目根目录建
tmpmod目录，复制一份干净的go.mod（删掉所有replace），运行GO111MODULE=on go mod download -x，观察最后几行 fetch 请求，定位卡在哪一个模块 - 用
go mod edit -dropreplace=example.com/badmod临时移除嫌疑项，再试go mod tidy；成功后再逐个加回，定位最小触发集 - 设置
GODEBUG=gocacheverify=0可跳过部分校验，但这只是掩盖问题，仅用于快速验证是否为校验逻辑阻塞
真正难处理的不是环本身，而是环里混着未发布的伪版本（v0.0.0- 开头）、被 // indirect 标记却实际参与构建的模块，以及 go.work 中跨项目的 replace 覆盖——这些场景下 go mod graph 输出不可信，得靠 go list -m -u -f '{{.Path}} {{.Version}} {{.Indirect}}' all 交叉验证。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
