Go vendor 模式为什么找不到新依赖

Go vendor 模式找不到新依赖，通常不是依赖没有下载，而是构建读取的 vendor 快照还没有更新。把包下载到模块缓存、在 go.mod 中记录版本、把实际使用的包复制进 vendor，是不同的事情；完成前两项不会自动完成第三项。

官方地址：https://go.dev/ref/mod

先确认当前模块和工作区，再在新增 import 已保存的前提下整理模块依赖、重新生成 vendor，最后显式使用 vendor 模式构建。不要靠清空缓存或手改 modules.txt 掩盖快照缺项。

自动启用 vendor 后，构建读取的位置变了

在单模块场景，go.mod 的 go 指令为 1.14 或更高、模块根目录存在 vendor 时，构建默认使用 vendor。也可以通过 -mod=vendor 明确选择。这里看的是模块声明和目录条件，不能只凭电脑安装了哪个 Go 版本判断。

这种模式把依赖源码集中在项目树中，便于团队一起交付。代价是新增依赖后必须维护这份快照。vendor 构建不会因为缓存里刚好有包就自动补缺；这也解释了为什么同一台机器切换构建参数后，问题表现会变化。

缓存、版本声明和源码快照各管一件事

源代码 import 决定项目使用哪些包，go.mod 记录模块需求，go.sum 记录相关校验信息，模块缓存保存下载内容。vendor 保存当前主模块构建和测试所需的依赖包副本，vendor/modules.txt 记录对应模块和包的信息。它不是模块缓存的镜像，也不保证复制每个依赖模块的所有目录。

例如，团队原本只使用某模块中的甲包，后来源码又导入同模块的乙包。即使模块版本没有变化，旧 vendor 也可能没有乙包。这类问题不一定表现为版本不一致，更可能直接报包无法解析。反过来，如果 go.mod 已改变而清单未同步，就需要处理 inconsistent vendoring，而不是继续复制单个源码文件。

先确定你正在处理哪个模块

以下是供读者执行的命令示例，本文没有在本机运行这些命令，也不展示虚构成功输出。在实际准备构建的目录执行：

# 查看工具链与模块上下文，避免在错误目录更新依赖
go version
go env GOMOD GOWORK GOFLAGS

确认 GOMOD 指向目标项目的 go.mod；检查 GOFLAGS 是否带有固定的 -mod 参数。GOWORK 若指向某个 go.work，说明当前处于工作区上下文。不要把单模块 vendor 和工作区 vendor 混用。

下节专门处理单模块项目：使用命令级 GOWORK=off 关闭工作区，不永久修改全局配置。只有当该模块本身能够独立解析依赖时才适合这样做；如果它依赖 go.work 中未发布的兄弟模块，应先决定正式交付采用工作区还是单模块方案，而不是盲目关闭工作区。工作区整体交付需要另按工具链支持的工作区 vendoring 规则处理。

新增导入保存后，重新生成整份 vendor

假设你在维护一个小型导出程序，新加的外部包已经写入真实源码并保存。进入目标模块根目录，在可获取依赖的环境中执行下面的单模块命令。先确保工作区没有需要保留的 vendor 手工改动，因为生成命令会重建这个目录。

# 任一步失败立即停止，避免用不完整快照继续构建
set -e
# 根据已保存的源码导入整理需求；可能访问网络并修改模块文件
GOWORK=off go mod tidy
# 从已解析的依赖生成 vendor；不要手工编辑其中的源码
GOWORK=off go mod vendor
# 明确要求从 vendor 解析外部依赖
GOWORK=off go build -mod=vendor ./...

如果团队必须固定新增依赖的版本，应先用 go get 指定经过项目决定的模块版本，再整理和生成快照；不要为了“补一个缺包”顺手升级所有依赖。这里没有预置任意第三方版本，避免将文章示例中的版本号误当成项目选择。

若 tidy 就报下载失败、私有仓库认证失败或 import 路径错误，应在这一层处理。生成命令需要能够读到依赖来源；最终 vendor 构建不查缓存，并不意味着准备 vendor 时也无需依赖材料。新增包还未出现在真实源码的 import 中时，单纯下载它也不能证明生成结果应包含它。

用同一套构建条件判断是否修好

上面的最后一个命令是提供给读者的最小构建检查，不是本文已经完成的运行证明。读者应看到命令正常退出、不再出现新增包缺失；如果仍报错，先看缺的是哪个包，再核对实际构建目录、源码导入和交付材料。

使用 vendor 交付时，把源码、go.mod、go.sum 和 vendor 的相应变更作为一组提交，避免只提交新增 import。不要在 vendor 内直接修补业务问题，下次重建会覆盖它；需要维护依赖时，应在依赖源或明确的替换方案中处理。

临时加 -mod=mod 能算修复吗？

不能。它绕开 vendor，可能从缓存或网络解析包，还可能调整模块需求。它能帮助区分两套依赖来源，但不代表 vendor 已完整，也不适合作为团队继续使用 vendor 时的最终交付结果。

go mod download 会更新 vendor 吗？

不会。它处理下载材料，不负责重建项目的 vendor 源码快照。

为什么不能直接复制缺失目录？

孤立复制容易漏掉传递依赖和清单变化。正常做法是根据同一份源码与模块声明整体生成，把错误暴露在生成阶段。

参考：Go Modules：Vendoring；go mod vendor 命令说明；工作区上下文说明。