Golang vendor使用教程【精通】

本文深入解析了 Go 1.14+ 中 vendor 机制的“失效之谜”：它并非 Bug，而是默认被彻底忽略的设计选择——必须严格满足 GO111MODULE=on、存在有效 go.mod 且显式启用 -mod=vendor 才能生效；同时直击三大痛点：漏包（因仅收录编译时真实 import 的依赖，测试、条件编译、私有库等极易遗漏）、离线构建失败（需同步关闭 GOPROXY=off 和 GOSUMDB=off，并确保 go.sum 完整可信），以及是否提交 vendor 到 Git 的权衡逻辑。文章不讲空泛概念，而是用可复现的错误现象、精准验证命令（如 go list -mod=vendor）和实操方案（如跨平台生成、强制包含测试依赖、日志排查）帮你真正掌控 vendor，让离线构建稳如磐石、依赖管理清晰可控。

go mod vendor 为什么生成了 vendor 却不生效

根本原因：Go 1.14+ 默认完全忽略 vendor/ 目录，哪怕它存在、结构完整，go build 仍会去拉远程模块——这不是 bug，是设计决定。

必须显式启用才能走 vendor 路径，且有两个硬性前提：

• GO111MODULE=on（Go 1.16+ 默认开启，但 CI 容器或旧脚本常被覆盖）
• 当前工作目录下有有效的 go.mod，且没误入父级模块路径（比如在子目录执行命令，却定位到上级 go.mod）

常见错误现象：go build -mod=vendor 还是打印 Fetching github.com/xxx@v1.2.3，或报错 cannot find module providing package xxx，但 vendor/github.com/xxx 明明存在。

验证方式：go list -mod=vendor ./... 应正常输出所有包路径；若失败，说明 vendor 未被识别。

go mod vendor 漏包了怎么办

它只复制「当前构建上下文实际 import 并参与编译」的包，不是 go.mod 里所有 require 都进 vendor/。

典型漏包场景：

• 仅在 *_test.go 中 import 的依赖（如 gotest.tools/v3），go build 不触发，go mod vendor 就跳过
• 用 //go:embed 或 //go:generate 间接引用，但没显式 import
• 带 // +build linux 等条件编译标签的文件，在默认 GOOS 下未被扫描
• 私有仓库依赖未配 GOPRIVATE，go mod vendor 静默失败而非报错

实操建议：

• 清理重做：rm -rf vendor/ && go mod tidy && go mod vendor
• 按目标平台生成：GOOS=linux GOARCH=amd64 go mod vendor
• 强制包含测试依赖：go test -mod=vendor ./... 后再 go mod vendor（部分版本有效）
• 加 -v 查日志：go mod vendor -v 看哪些模块被跳过及原因

离线构建时 go build -mod=vendor 还是失败

vendor 只解决「源码来源」，但 Go 工具链仍有多个环节会悄悄联网：模块校验、go list 解析、checksum 核对等。

必须同时关闭两个关键网络开关：

• GOPROXY=off：禁用模块代理，否则 go list 或 go mod download 阶段仍会连 proxy.golang.org
• GOSUMDB=off：禁用校验和数据库，否则 go build 会校验 go.sum 时尝试访问 sum.golang.org

验证是否生效：go env GOPROXY GOSUMDB 输出应为 off。

更关键的是：go.sum 必须完整。离线前务必在线环境运行 go mod verify，确认无 checksum mismatch；否则即使 vendor 齐全，构建也会因校验失败中断。

vendor 目录要不要提交到 Git

没有绝对答案，取决于团队对「构建确定性」和「仓库体积」的权衡。

提交的适用场景：

• CI/CD 环境完全隔离（无外网、无 proxy）、要求 100% 可重现
• 交付给客户或第三方的源码包，需开箱即用
• 审计敏感项目，要求所有依赖代码可追溯、可扫描

不提交的适用场景：

• 小型内部项目，依赖少、更新频繁，vendor/ 占用百 MB+，拖慢 git status 和克隆速度
• 团队已统一使用可信 proxy + checksum 校验，信任模块缓存一致性

如果提交，注意两点：

• vendor/modules.txt 是自动生成的，应加入 .gitignore（Go 1.18+ 已弃用该文件，但旧版本仍存在）
• vendor/ 下的 go.mod 是只读快照，每次 go mod vendor 都会重写，切勿手动编辑

真正复杂的地方不在 vendor 本身，而在于 Go 工具链对网络的隐式依赖——从解析、校验到缓存刷新，每个环节都可能悄悄往外探一次头。离线不是加个 -mod=vendor 就完事，得把整个工具链的“联网反射弧”都堵死。

到这里，我们也就讲完了《Golang vendor使用教程【精通】》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！