go mod download报错主因是GOPROXY或GOPRIVATE配置失效，非依赖层数问题；国内须设GOPROXY=https://goproxy.cn,direct，私有域名须完整加入GOPRIVATE，验证用go env GOPROXY/GOPRIVATE，临时调试可GOPROXY=direct go mod download -v。
go mod download 报错 “module lookup failed” 或 timeout，根本不是层数问题
这类报错 90% 以上和“多层依赖”无关，而是 GOPROXY 或 GOPRIVATE 配置失效导致的网络路径错误。Go 不会因为依赖层级深就拒绝下载——它只关心模块路径是否可达、校验和是否匹配。
常见现象包括：module lookup failed、Get "https://proxy.golang.org/...": dial tcp: i/o timeout、403 Forbidden（尤其私有库）。
- 先执行
go env GOPROXY GOPRIVATE，确认两者都已设置且无拼写错误；国内用户必须设为可信镜像，例如：go env -w GOPROXY="https://goproxy.cn,direct" - 私有仓库域名（如
git.internal.company.com）必须完整列入GOPRIVATE，通配符git.internal.company.com/*有效，但git.internal.*无效 - 临时验证：运行
GOPROXY=direct go mod download -v，若成功说明是代理问题；若仍失败，用curl -I https://git.internal.company.com/your/module/@v/v1.2.3.info测试直连权限
go.sum 缺失或校验失败，别手动补，用工具修
go build -mod=readonly 报 missing go.sum entry，本质是某个 require 条目没对应 hash 记录。这不是“多层”导致的缺失，而是模块被引入但未完成校验流程。
典型触发场景：刚 go get 新依赖但没运行 go mod tidy，或 CI 环境拉取了旧 go.mod 却没同步 go.sum。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 直接执行
go mod download，它会自动补全所有缺失的校验和到go.sum - 若某模块在
go.sum中有多个 hash 行（对应不同版本），属正常现象——Go 允许同一模块多版本共存于校验文件，只要最终选用版本唯一 - 严禁手动编辑
go.sum：工具链会校验其完整性，手改后go build直接拒绝加载
间接依赖版本冲突，靠 replace 不能根治，得用 require + go mod tidy 控制选型
当 go list -m all | grep some/pkg 显示多个版本，而实际构建失败，说明 MVS（最小版本选择）挑出了不兼容版本。此时 replace 只是绕过约束，不解决兼容性。
真正可控的做法是让该模块成为“显式依赖”，提升其在 MVS 中的优先级：
- 运行
go get some/pkg@v1.2.3，它会在go.mod中添加require行（末尾带// indirect） - 手动删掉该行末尾的
// indirect注释，使其变成直接依赖——MVS 会优先满足它提出的版本要求 - 再跑一次
go mod tidy，清理冗余indirect条目，并重算整个依赖图 - 验证：执行
go list -m some/pkg，输出应为v1.2.3；再用go mod graph | grep some/pkg确认所有引用路径都收敛到该版本
CI 构建失败时，最容易被忽略的是 replace 指向本地路径
本地调试时常用 replace github.com/foo/bar => ../bar，但一旦提交到 Git 并进入 CI，../bar 路径必然不存在，导致 go build 直接报 cannot find module。
这不是“多层依赖”的锅，而是 replace 写法本身与环境强耦合。
- CI 前务必检查
go.mod中所有replace行：凡含../、./或绝对路径的，全部删除或注释掉 - 临时 fix 的替代方案：用 commit hash 替代本地路径，例如
replace github.com/foo/bar => github.com/foo/bar v0.0.0-20260715102030-abcdef123456 - 长期解法：把修复提交到上游，或 fork 后发版，再
go get正式 tag——否则每次 CI 都要人工干预
indirect 模块悄悄升级后改了默认行为（比如日志加了 trace 字段、HTTP client 默认启用了 gzip），这种变化不会报错，但会让线上行为突变。比盲目控制层数更有效的做法，是定期用 go mod graph 结合 git blame go.mod 追溯变更源头，盯住那些版本跳升幅度大的 indirect 条目。 
