Go编译期静态分析发现import语句构成有向环即报错，与下载、多层或间接依赖无关；go mod download不检查依赖图，报错必因go build等命令触发；修复须抽离共享类型、定义接口或合并包。
不存在“多层引用引起的依赖下载循环报错”——Go 的 go mod download 或 go build 报 import cycle not allowed，100% 是包级 import 语句构成的有向环，和“下载”“多层”“间接依赖”完全无关。所谓“循环报错”，只发生在编译期静态分析阶段，不是网络、代理或模块解析失败。
为什么 go mod download 不会报 import cycle 错误
go mod download 只拉取代码、校验 hash、写入本地缓存，它不解析 import 图，也不检查包依赖结构。如果你在执行 go mod download 时看到 import cycle not allowed，说明你实际运行的是 go build、go test 或 go list 等触发构建的命令（比如 CI 脚本里混用了），不是下载本身出问题。
- 验证方式：单独跑
go mod download -v，看输出是否全是downloading ...行；如果有import cycle，一定是后面跟了其他命令 -
go mod graph输出里出现A → B → A这类回边，才是真循环；而go list -m all里一堆// indirect是正常现象，不是循环 - 常见混淆点：把
go get github.com/x/y@v1.2.0后立即go build失败，误以为是下载引发循环——其实是新引入的y包内部 import 了你的某个包，才暴露了已有隐式环
真正要查的是哪个包在 import 哪个包
Go 编译器从不隐藏循环路径。Go 1.21+ 会直接打印完整闭环链，例如：
import cycle not allowed:
github.com/your/app/order imports github.com/your/app/user
github.com/your/app/user imports github.com/your/app/payment
github.com/your/app/payment imports github.com/your/app/order
如果版本较旧或输出被截断，用这两条命令定位：
立即学习“go语言免费学习笔记（深入）”；
-
go list -f '{{.ImportPath}} -> {{join .Imports " -> "}}' ./... | grep -E 'order|user|payment'—— 查所有包的 import 链，过滤关键词 -
go mod graph | awk '$1 ~ /order|user|payment/ {print}' | grep -E 'order.*user|user.*payment|payment.*order'—— 快速筛出可疑边 - 特别注意
*_test.go文件：测试文件 import 了pkgA和mockB，而mockB又 import 了pkgA的类型，极易构成隐式环
修复时别碰 go.mod 里的 replace/exclude
replace 和 exclude 只影响模块版本选择，对 import 图零作用。它们不能打破、绕过或隐藏 import cycle 错误，强行加只会让问题更难排查。
- 错误操作：看到
pkgA和pkgB循环，就在go.mod里写replace pkgB => ./local-b—— 编译照样失败，且本地路径在 CI 中失效 - 正确做法：先用上面命令确认闭环路径，然后选一个节点做解耦。90% 的 case 适用这三种改法之一：
• 把共用 struct/error 提到新包domain或types，双方都只 import 它
• 在上层包（如internal/port）定义接口，调用方持有接口，实现方实现它，但不互相 import
• 合并两个包——如果它们始终一起变更、无法独立测试、文档里也写“强耦合”，那就别硬拆 - 切忌在
init()函数里跨包调用：哪怕没写import，只要函数体里用了对方包的符号，编译器仍能静态分析出依赖
最易被忽略的点：循环往往藏在测试文件或 embed 生成代码里，而不是主逻辑；修复后务必运行 go list -f '{{.Deps}}' ./... 确认闭环消失，而不是只看编译过了就认为解决。
