go 库不应自带 vendor 目录，但需提供可复现的依赖声明机制（如 go.mod）；使用 go get 时应保证依赖可直接解析，而 vendoring 工具（如 govendor）的问题应由使用者自行解决，库作者只需提供标准化、工具无关的依赖描述。
go 库不应自带 vendor 目录，但需提供可复现的依赖声明机制（如 go.mod）；使用 go get 时应保证依赖可直接解析，而 vendoring 工具（如 govendor）的问题应由使用者自行解决，库作者只需提供标准化、工具无关的依赖描述。
在 Go 生态中，一个被广泛接受的原则是：库（library/package）不携带 vendor 目录，仅应用（application）才应 vendor 依赖。这一设计源于 Go 的模块化哲学——库应保持轻量、可组合、无构建侧副作用。你的库 docserv 正确遵循了该原则，但 Jenkins 构建失败的根本原因并非库设计失误，而是依赖解析环境不一致所致。
✅ 正确做法：优先采用 Go Modules（推荐）
自 Go 1.11 起，官方模块系统（go mod）已成为标准依赖管理方案。请立即为你的库初始化模块：
cd $GOPATH/src/github.com/gerbenjacobs/docserv go mod init github.com/gerbenjacobs/docserv go mod tidy # 自动分析 import 并写入 go.mod/go.sum
这将生成 go.mod（声明最小版本要求）和 go.sum（校验依赖完整性）。用户执行 go get github.com/gerbenjacobs/docserv 时，Go 工具链会自动按 go.mod 解析并下载兼容版本——无论本地是否启用 GO111MODULE=on，只要使用较新 Go 版本（≥1.16 默认开启），即可保证构建可重现。
⚠️ 注意：govendor 是已淘汰的第三方工具（自 Go 1.11 起不再维护）。Jenkins 构建失败，本质是其环境未启用模块模式或缓存了旧版依赖。解决方案不是让库“适配 govendor”，而是推动构建环境升级至标准模块工作流。
❌ 不推荐方案：手动 subtree/vendoring 库依赖
答案中提到的 git subtree 方案虽技术可行（如 xxhash 示例），但存在明显缺陷：
- 违反 Go 库设计规范，增加维护成本；
- 子树更新易出错，且无法自动校验依赖哈希；
- 与 go list -m all、go mod graph 等标准诊断命令不兼容；
- 对消费者透明性差（vendor 内容不可被 go get 感知）。
除非你明确要求 零外部网络依赖（如离线嵌入式场景），否则不应在库中引入任何 vendoring 逻辑。
?️ 最佳实践总结
| 场景 | 推荐操作 |
|---|---|
| 库作者 | 提供 go.mod + go.sum；在 README 中声明最低 Go 版本（如 Go ≥ 1.19）；避免 vendor/ 目录；使用 go test ./... 验证跨版本兼容性 |
| 库使用者（含 CI） | 确保 Jenkins agent 使用 Go ≥ 1.16，设置 GO111MODULE=on；构建前执行 go mod download 预热模块缓存；禁用 GOPATH 模式 |
| 向后兼容 | 若需支持旧版 Go（ |
最后，请更新你的 README：将 go get 指令明确为 GO111MODULE=on go get github.com/gerbenjacobs/docserv，并添加一行说明：“本库基于 Go Modules 构建，建议在 Go 1.16+ 环境中使用”。这才是对用户和生态最负责任的做法。
