vendor目录不会自动生效，必须显式加-mod=vendor参数才能启用；否则go build仍联网解析go.mod/go.sum，离线时直接报错。
vendor 目录不是自动生效的开关
很多人以为只要项目里有 vendor/ 目录，go build 就会自动用它——这是错的。从 Go 1.14 开始，vendor/ 必须配合 -mod=vendor 显式启用，否则工具链仍会联网解析 go.mod 和 go.sum，离线时直接报 cannot find module。
常见错误现象：
- CI 构建失败，提示找不到某个依赖模块，但本地
vendor/里明明有 -
go test在离线环境报 checksum mismatch，而go build -mod=vendor却能过
原因在于：go test、go list、go install 等命令默认不走 vendor 模式，必须统一加 -mod=vendor 参数。IDE（如 VS Code + gopls）也需在 settings.json 中配 "go.toolsEnvVars": {"GOFLAGS": "-mod=vendor"} 才能识别。
go mod vendor 不等于依赖锁定完成
go mod vendor 只是把 go.mod 里声明的依赖源码拷进 vendor/，它不校验、不补全、也不清理冗余。很多团队误以为执行完这条命令就万事大吉，结果上线后发现行为异常。
立即学习“go语言免费学习笔记（深入）”；
关键注意事项：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
-
go mod vendor不会自动更新go.sum；若新增或变更依赖，必须额外跑go mod tidy再go mod vendor，否则go build -mod=vendor会因校验失败中断 - 如果
go.mod里有replace指向本地路径（如replace example.com/a => ../a），go mod vendor默认忽略该替换，vendor/里不会包含对应代码 - 私有仓库依赖（如
git+ssh://...）在vendor/后可能丢失.git信息，导致go list -m all显示版本为devel，破坏构建可重现性
嵌套 vendor 是典型历史包袱，必须清除
第三方库（比如 github.com/orloffm/cat）若自己提交了 vendor/ 目录，你的主项目执行 go mod vendor 后，vendor/github.com/orloffm/cat/vendor/ 会被原样保留——造成同一依赖（如 toy）在 vendor/ 下出现两份，且版本可能不一致。
这不是 Go Modules 的设计意图，而是早期 Glide 或 dep 用户遗留的习惯。现代做法是：
- 库作者应在
.gitignore中排除vendor/，不提交它 - 主项目若发现嵌套
vendor/，应手动删除（如find vendor -name vendor -type d -delete），再go mod vendor重建 - CI 流水线中可加检查：运行
find vendor -name vendor -type d | head -n1，非空即告警
vendor 目录必须和 go.mod 严格同步
vendor/ 是 go.mod 的快照，不是替代品。它里面不能、也不该有 go.mod 文件；一旦混入，Go 会报 go: inconsistent vendoring 错误。
容易被忽略的点：
- 有人手动
cp第三方包进vendor/，但没在go.mod中声明——go build -mod=vendor会静默跳过，但go list -m all无法反映真实依赖图 -
go.sum和vendor/必须匹配：删掉go.sum或让它过期，go build -mod=vendor会直接失败，报checksum mismatch - 提交
vendor/到 Git 是必要的，但要注意体积——某些包（如含大量二进制或测试数据）会让目录膨胀，可考虑.gitattributes配置vendor/** diff=none减少 diff 噪音
vendor 的本质是“确定性快照”，不是“隔离沙盒”。它起作用的前提，是你始终让 go.mod、go.sum、vendor/ 三者保持原子一致性——任何一环脱节，都会在离线、CI 或跨环境部署时暴露问题。
