先用go mod graph或go list -f '{{.ImportPath}} -> {{join .Imports " -> "}}' ./画出导入图，结合grep定位pkgA → pkgB → pkgA类回边；注意_test.go、embed和generate可能引入隐式循环。
构建报错时，go build 给的错误信息往往只暴露表层现象，真正卡住的地方通常在导入路径、版本校验或隐式依赖里——先别急着改代码，得让工具把依赖关系“画出来”。
看到 import cycle not allowed 怎么快速定位回边
Go 编译器不告诉你哪条路径成环，只抛一句错误。最有效的办法是生成导入图：
- 运行
go list -f '{{.ImportPath}} -> {{join .Imports " -> "}}' ./ | grep -E 'pkgA|pkgB'，快速筛出可疑包之间的引用链 - 更直观的是
go mod graph | grep -E 'pkgA|pkgB'，直接找pkgA -> pkgB -> pkgA这类回边 - 注意：
_test.go文件也参与构建期导入检查，测试文件里偷偷 import 了生产代码，又反过来被生产代码 import，这种环最难发现 - 用了
//go:embed或//go:generate？生成的代码可能隐式 import 回源包，导致原本不循环的结构突然报错
go build 报 checksum mismatch 或 inconsistent dependencies 怎么查
这类错误本质是模块校验快照和实际内容对不上，或者多个路径拉了同一模块的不同版本：
- 先跑
go mod verify，确认所有模块的go.sum是否有效；失败说明本地缓存或网络代理污染了下载内容 - 用
go mod graph | grep 'module-name'看谁在间接拉这个模块，再结合go list -m all | grep module-name确认实际加载版本 - 如果输出里同时出现
v1.8.0和v2.0.0+incompatible，就是高风险信号：新工具链会拒绝这种混合，得统一升级或降级 - 别直接
go mod tidy—— 它可能按旧规则选版本，反而加剧冲突；优先用go mod why module-name找出是谁“拖后腿”
undefined: Xxx 报错是版本升了还是 Go 版本低了
这类错误常出现在升级模块或编译器后，表面是符号找不到，实则是 API 兼容性断层：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 先确认当前 Go 版本：
go version；再查目标模块的go.mod里声明的go X.Y，两者必须兼容（例如errors.Is需 Go 1.13+） - 用
go doc module-name/pkg.FuncName查该函数是否存在于当前模块版本中；无结果说明已弃用或重命名 - 常见翻车点：
golang.org/x/net/http2.Transport字段从AllowHTTP2改为ForceHTTP2，升级后不改代码就报 undefined - 如果是 internal 路径访问失败（如
cannot load github.com/user/repo/internal/util），说明新版模块已将该路径设为私有——只能换用导出的公共 API，或临时replace回退
容器化后构建成功但运行时报错，环境差异在哪
Docker 构建阶段成功不代表运行时没问题，基础镜像、CGO、环境变量三者最容易漏检：
- 基础镜像是否含 CGO 依赖？比如用了
golang:1.21-alpine却没装musl-dev，或项目启用了CGO_ENABLED=1但镜像里没 gcc - 检查
Dockerfile是否遗漏RUN go mod download，尤其当go.mod里有replace或私有仓库时，COPY . .后再go build可能因缓存跳过下载 - 环境变量是否透传？比如配置里读
os.Getenv("DB_HOST")，但docker run没加-e DB_HOST=...，运行时就会 panic - 端口是否暴露且映射？
EXPOSE 8080只是声明，还得docker run -p 8080:8080才能访问；否则程序启动成功，但外部连不上
构建报错最麻烦的不是错误本身，而是它常常掩盖了多个问题叠加：比如一个 import cycle 可能由测试文件触发，而修复它后又暴露出 checksum mismatch，接着运行时才发现环境变量缺失。每次只专注解决一个错误，并用 go mod graph 或 go list -deps 验证改动是否引入新依赖路径，比反复试错更稳。
