Go编译器在build阶段强制检查import循环依赖并报错，需用go list -f '{{.Deps}}'逐层追查、go mod graph找回边、gopls实时标红定位环路路径，而非运行时检测。
go build 报 import cycle not allowed 怎么快速定位环路
这不是运行时死锁，而是构建期静态检查失败——Go 编译器发现 import 图中存在闭环，立刻终止构建。你不需要写检测逻辑，但必须快速从报错里挖出那条隐藏的路径。
编译错误只显示类似 import cycle not allowed: a imports b imports a，中间环节被省略。实际环路常是 a → b → c → a 这种三跳结构，得手动补全：
- 对每个疑似包执行
go list -f '{{.Deps}}' pkgpath，再用grep逐层追查，比如go list -f '{{.Deps}}' b | grep a看是否间接引入 - 特别注意
_test.go文件：它们会引入额外 import，且错误信息里常带(test)后缀，容易漏掉 - 如果用了
replace或vendor，加-mod=readonly参数跑go list，否则查的是线上路径而非真实构建行为
go mod graph 为什么能一眼看出回边
go mod graph 输出模块级依赖关系，适合发现因 replace、多版本 alias 或间接引入导致的隐藏环。它不直接标环，但能帮你聚焦可疑连接。
执行 go mod graph | grep 'your-module-name'，重点找反向指向自己的边，例如同时出现：
立即学习“go语言免费学习笔记（深入）”；
your-module/a your-module/b<br>your-module/b your-module/a
说明已构成环。若输出行数巨大，先用以下命令找出高频依赖包（往往是环路枢纽）：
go mod graph | awk '{print $1}' | sort | uniq -c | sort -nr | head -10
注意：go mod graph 对 vendor 目录不敏感，项目用了 vendor 的话，需先 go mod vendor 再跑，否则结果失真。
gopls 实时标红 import 行比等报错快得多
VS Code + Go 插件默认启用 gopls，它会在保存时实时分析整个 workspace 的 import 图，并把触发循环的那条 import 语句直接标红——这是最省力的方式。
但它只标「当前文件中造成环的那行 import」，不是环上所有包。有时你需要点开被标红的包，再看它的 import 是否也红了：
- 确认 VS Code 底部状态栏显示的是你预期的 workspace 根；如果项目根目录下有多个
go.work或嵌套 module，gopls可能加载不全 - 终端里可开
gopls调试日志："go.languageServerFlags": ["-rpc.trace"]，日志里会出现类似import cycle detected: a → b → c → a的完整路径
接口提取位置错一个就绕回循环依赖
重构时提接口本为解耦，但放错包反而加剧循环。原则只有一条：接口定义必须放在「依赖它的一方」的对面包里——也就是调用方不持有接口，实现方也不定义接口，而是由第三方（通常是上层或共享包）声明。
常见错误：
- 放在实现方包里 → 调用方被迫
import实现细节，违背依赖倒置 - 放在调用方包里 → 实现方得
import调用方，包职责混乱，且容易引发循环（比如handler定义Repo，repo/sql又想import handler做日志） - 新建
internal/port是稳妥选择，但这个包不能import任何业务实现包，否则又绕回去了
真正难的不是找到环，而是改完一处后，另一处悄悄冒出新环——尤其当 //go:generate 或 go:embed 生成的代码隐式引入了反向依赖。
