冷门库易在ci或新环境“消失”是因为其托管平台不稳定，go mod download无缓存和fallback机制，仅依赖go.sum校验哈希但无法解决下载失败问题；vendor目录是唯一可靠方案，必须提交到git并配合go build -mod=vendor使用。
为什么冷门库容易在 CI 或新环境里“消失”
冷门第三方库常托管在小众 Git 服务、个人仓库或已归档项目中，一旦源站下线、权限变更或 tag 被 force push，go mod download 就会失败。Go 默认不缓存这类模块，也没有 fallback 机制——它只认 go.sum 里的哈希，但哈希对不上就直接报错：failed to download ...: not found 或 checksum mismatch。
vendor 目录是唯一可靠的选择
对冷门库，go mod vendor 不是“可选优化”，而是必须步骤。它把所有依赖（包括冷门库的完整代码）复制进 vendor/，后续构建完全绕过网络拉取。
- 执行
go mod vendor后，检查vendor/下是否包含该冷门库路径（如vendor/github.com/unknown-author/obscure-pkg） - 务必把整个
vendor/提交到 Git —— 不要忽略、不加.gitignore - CI 构建时显式启用 vendor 模式：
go build -mod=vendor，否则 Go 仍会尝试联网 - 注意：若冷门库本身含
replace或引用其他不可达模块，go mod vendor会失败，需先手动 fix 它的go.mod
go.sum 不能替代 vendor
go.sum 只存校验和，不存代码。即使你反复 go mod download 成功并提交了 go.sum，只要远程源消失，下次 go mod download 仍会卡住——因为 Go 需要重新下载并比对哈希，而下载环节已不可达。
常见误操作：“我已经提交了 go.sum，应该够了” → 实际上毫无作用。冷门库的脆弱性不在校验环节，而在获取环节。
私有或临时镜像只是辅助手段
设 GOPROXY=your-proxy.example.com 并缓存冷门库，有一定帮助，但引入额外运维负担；且一旦 proxy 故障或配置错误，问题照旧。相比而言，vendor 是零依赖、零配置、100% 离线可用的方案。
真正关键的不是“怎么代理”，而是“代码是否就在本地”。冷门库没有社区兜底，你得自己当它的 CDN。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
