Go vendor 目录为什么没有包含新增依赖

Go的vendor目录不是模块缓存，也不会在每次新增依赖后自动刷新。只有go.mod里多了一条require、或已经下载模块，并不表示相关包一定会出现在vendor中。先确认源码或本模块测试确实引用了该包，再在正确模块范围运行 go mod vendor；使用工作区时，还要区分模块级vendor与工作区级vendor。

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

面对“本地能编译，CI却说vendor缺包”的情况，我会先对齐三件事：新增import是否已经落盘，生成快照的是哪个模块，以及本地与CI是否采用相同构建模式。这是一套排查方法，不是某个真实项目的故障复盘。

先明确这次依赖变更的范围

升级或新增模块后，旧vendor仍代表上一次生成的依赖快照。把go.mod的新版本号与旧vendor内容放在一起，可能触发inconsistent vendoring，或者在使用新包时暴露缺失。不要先手工复制一个目录进去，让清单与实际内容继续分裂。

区分模块声明与实际包引用

go mod vendor围绕主模块构建与测试所需的包生成副本，不是把require涉及的每个模块完整仓库全部复制。一个模块能有很多包，项目只用其中一部分时，vendor目录比源码仓库小是正常的。

仅被外部依赖自身测试引用、而主模块构建和测试不需要的包，不会因为存在于上游仓库就全部带入。构建标签除ignore外通常不会把相应条件文件的依赖排除在vendor计算之外，因此不能笼统地把缺包归咎于“当前系统没有编译那个文件”。

如果生成代码会新增import，应先生成并保存代码，再整理和生成依赖快照。若工具只通过独立的go install命令安装，不能推断它已成为本模块所需包；工具管理方式应按项目约定单独确定。

按单模块范围重新生成vendor

先确认当前工作目录属于预期模块。以下命令面向POSIX Shell中的单模块维护，GOWORK=off只对对应命令生效，避免父目录go.work改变本次操作范围：

# 在目标模块目录检查真实入口与构建标志。
go version
go env GOMOD GOWORK GOFLAGS
# 源码import已经保存后，整理单模块的依赖声明与摘要。
GOWORK=off go mod tidy
# 重建vendor；已有vendor中的手工修改会被替换，先保存必要补丁。
GOWORK=off go mod vendor
# 查看声明、摘要、清单及源码快照的变化。
git status --short
git diff -- go.mod go.sum vendor/modules.txt

命令供读者在自己的项目执行，本文没有运行或声称检查通过。tidy可能新增或移除依赖，甚至为缺失import解析版本；需审阅变化是否符合本次迁移目标。不要把“命令没报错”当成依赖版本选择已经经过业务审核。

go mod vendor会重建vendor，不能把手改上游源码当作稳定维护方式。如果确实有依赖修复，应通过受控分叉、版本或replace记录表达，再重新生成快照。手工改modules.txt同样不能补齐缺失包源码。

检查时应查找真实导入路径。例如模块example.com/team/codec中的包位于json子目录，期望路径应是vendor/example.com/team/codec/json，而不只是寻找名为codec的顶层目录。这里是路径示意，不指向真实依赖。

工作区与构建入口要保持一致

若go env GOWORK返回了一个go.work路径，先决定交付目标是单个模块，还是整个工作区。单模块快照可显式关闭工作区后在该模块生成；需要工作区级快照时，使用支持相应命令的工具链并遵循工作区vendor规则。

# 先阅读本机工具链对工作区vendor的帮助，再按项目策略执行。
go help work vendor
# 仅用于已经决定维护工作区级依赖快照的项目。
go work vendor

不要一边在单模块目录生成vendor，一边让CI从另一个工作区根目录读取快照，再把差异归因于依赖没有下载。也不要只为让某个命令成功永久修改全局GOWORK设置，而忽略团队的工作区策略。

对单模块构建，go.mod声明Go 1.14或更高且存在vendor时，默认行为可能使用vendor。显式-mod=mod则会选择模块解析方式，本地因此成功并不证明CI的vendor模式也完整。排障时把GOFLAGS与构建命令一起比较。

把依赖快照作为一组变更提交

依赖迁移应把新增源码import、go.mod、go.sum和vendor快照作为同一组可追溯变更。vendor/modules.txt记录模块与版本信息，不等于所有模块完整源码都必须存在；反过来，有源码目录也不能替代清单一致性。

# 在单模块交付场景明确使用vendor构建，并运行相应测试。
GOWORK=off go build -mod=vendor ./...
GOWORK=off go test -mod=vendor ./...
# 提交前确认vendor没有被忽略规则或打包脚本遗漏。
git status --short --untracked-files=all

预期是vendor模式下不再报告新增导入包缺失，依赖快照与声明一致。测试仍需覆盖升级后的业务行为；这些是读者的回归建议，不是本文已经运行的结果。如果CI使用不同GOOS、GOARCH或构建标签，也应按实际发布目标分别构建。

为什么go.sum里有记录，vendor里却没有整个模块？

摘要记录与包副本承担不同职责，历史或间接依赖记录不能当作“整个模块应当被复制”的清单。

只执行go mod download够吗？

不够。它准备模块缓存，不负责重建vendor目录；已经存在的快照仍需显式更新。

新增包仍没有进入vendor，应再看哪里？

检查import是否保存在正确模块、是否位于嵌套模块或被ignore约束排除，以及生成命令是否中途失败。先修复报错，不要接受半完成快照。

维护vendor时，我会把它看作依赖变更的交付产物：包引用决定需要什么，模块范围决定从哪里生成，构建模式决定实际读取哪一份。

官方资料：模块vendor规则；Go命令文档。