go 模块（go.mod）不支持循环依赖，但包级导入循环会被编译器拒绝；错误源于编译期符号解析，而非模块系统；可用 go list 或 goda 定位环路，解法包括抽离接口、函数参数传递或延迟加载。
Go 语言的模块（go.mod）本身不支持循环依赖——一旦出现，go build 或 go test 会直接报错，根本不会运行。真正需要处理的是**包级导入循环**（import cycle），也就是两个或多个 .go 文件所在的包互相 import 对方，这在 Go 中是编译时禁止的。
为什么 go.mod 不会循环依赖，但包导入会报错？
Go 模块系统只管理版本和依赖关系图，它不参与编译期的符号解析；而包导入循环发生在编译阶段，由 Go 编译器（gc）检测并拒绝。错误信息通常是：
import cycle not allowed package example.com/a imports example.com/b imports example.com/a注意：这个错误里的路径是包路径（如 example.com/a），不是模块路径（example.com）。模块可以依赖另一个模块，只要它们的包之间不形成导入环。
如何快速定位 import cycle 的源头？
用 go list 配合 -f 模板可导出依赖图，再人工或脚本分析环路：
立即学习“go语言免费学习笔记（深入）”；
- 运行
go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...查看每个包显式导入了哪些包 - 对输出做拓扑排序或用工具如
goda（go install github.com/kisielk/goda@latest）可视化依赖：goda graph | dot -Tpng -o deps.png - 常见诱因：把接口定义放在 A 包，实现放在 B 包，但 B 又反向 import A 里的某个具体类型（比如
A.Config）——其实只需把接口和其依赖的精简类型一起抽到新包 C
三种可靠解法及其适用场景
没有“银弹”，选哪种取决于你控制代码边界的自由度：
- 抽离公共接口/类型到第三方包：最常用。例如
a/service.go定义type UserService Interface，b/impl.go实现它，但两者都 import 新建的c/contract包，而非互相 import - 用函数参数或回调替代包级依赖：当 B 包只需调用 A 包某个能力，且 A 不需要 B 的任何结构体时，把 A 的依赖声明为函数参数（如
func DoWork(fetcher Fetcher)），让调用方传入实现，避免 import - 延迟加载（
import _ "xxx"+ 初始化逻辑）：仅适用于插件式扩展，比如 A 包注册 handler，B 包在init()里调用A.register(...)。此时 B 仍需 import A，但 A 不 import B —— 关键是确保 A 的注册接口不引用 B 的任何类型
容易被忽略的隐式循环陷阱
有些循环不体现在 import 语句中，但依然会被编译器捕获：
- 嵌套结构体字段引用对方包的类型：
type Req Struct { User b.User }在 a 包中，而 b 包又用了 a 包的Req—— 即使没写import "a"，如果b.User的定义里嵌套了 a 的类型，也会触发循环 - 全局变量初始化依赖：包 A 的
var x = b.NewY()，而包 B 的func NewY() *Y内部调用了a.DefaultConfig()—— 这属于初始化顺序循环，Go 会报initialization loop - 测试文件（
*_test.go）引发的循环：主包a导入b，而a/a_test.go又 importb的测试辅助函数，若这些函数内部引用了a的类型，就可能绕过常规检查形成环
这类问题往往在添加新字段、重构初始化逻辑或合并测试工具包时突然暴露，查错时务必检查类型定义的完整展开链，而不仅是 import 行。