Go vendor/modules.txt 与 go.mod 不一致时怎么恢复

项目明明没有改依赖，执行 go test 却提示 vendor/modules.txt 与 go.mod 不一致，通常不是清单本身坏了，而是模块图已经变化，vendor 还是旧投影。恢复的稳妥顺序是：先让 go.mod 和源码导入准确，再执行 go mod vendor，最后用 -mod=vendor 明确验收。不要直接编辑 vendor/modules.txt，下次生成 vendor 时仍会被覆盖。

搭出最小复现仓库并确认 vendor 模式

先把问题缩小到一个有 go.mod、源码包和根目录 vendor 的小项目。Go 1.14 及以上，当根目录存在一致的 vendor/modules.txt 时，构建命令可能自动采用 vendor；为了排查不受默认行为影响，建议先显式查看三种模式。

# 先确认 Go 版本和当前模块根目录
go version
go env GOMOD

# 分别观察模块模式；这些命令不修改 vendor
go list -mod=vendor -m all
go list -mod=mod -m all
go list -mod=readonly -m all

如果第一条直接报 modules.txt 不一致，问题发生在“vendor 清单与 go.mod 的版本描述不匹配”；如果 -mod=mod 也提示 go.mod 需要更新，先修模块描述，不要急着重建 vendor。

让 go.mod 和模块图先恢复准确

vendor 是构建用的依赖副本，不是依赖真相。先检查最近是否有人改过直接导入、require、replace、exclude 或 Go 版本；确认这些改动就是团队需要的，再整理模块文件。

# 在仓库根目录执行；先让模块描述贴合源码导入
go mod tidy

# 只查看依赖描述的变更，避免把 vendor 差异和模块差异混在一起
git diff -- go.mod go.sum

go mod tidy 可能新增或删除间接依赖，也可能更新 go.sum。这一步出现变化并不代表 Go “偷偷改坏了项目”，而是说明原来的模块描述没有准确反映当前代码。若项目使用本地 replace，先确认替代目录的 module 路径一致；若是私有模块，先确保当前环境能访问它。

用 go mod vendor 重建 modules.txt

模块文件确认后，再由 Go 工具重建整个 vendor 目录。该命令会根据主模块需要构建的包复制依赖，并生成 vendor/modules.txt；这样清单与当前模块图来自同一次计算。

# 从当前 go.mod 和源码重新生成 vendor 及 modules.txt
go mod vendor

# 先看生成结果是否只包含预期的依赖变化
git status --short
git diff --stat -- go.mod go.sum vendor

不要只删除 vendor/modules.txt 或只复制某个依赖目录。缺清单会让版本信息不完整，手工补一行也可能漏掉模块的显式标记。团队通常应提交 vendor/、vendor/modules.txt 与本次确实需要的 go.mod/go.sum 变化。

用明确的 -mod 参数验收

修复后至少做一次 vendor 模式测试，并把结果与非 vendor 模式区分记录。这里关注的是两种模式是否都符合项目预期，不是为了强行让它们产生完全相同的缓存路径。

# 强制只使用根目录 vendor，适合离线或提交 vendor 的构建
go test -mod=vendor ./...

# 需要从模块缓存或代理解析时，显式绕过 vendor
go test -mod=mod ./...

# CI 检查模块文件不可被自动修改
go test -mod=readonly ./...

# 最后确认工作区只留下计划内的依赖文件变更
git diff --check
git status --short

常见问题

go mod vendor 会不会修改 go.mod？

它的主要职责是生成 vendor；如果 go.mod 本身不准确，先用 go mod tidy 或明确的依赖调整解决，再重建 vendor，不要把两个动作混成一次手工修补。

为什么 go list -m all 看不到 vendor 里的每个包？

模块列表以 go.mod 中的模块为边界，不等于 vendor 目录下的每个源码包清单。需要检查 vendor 构建时，用 go list -mod=vendor 或 go test -mod=vendor 验证。

只在本机能通过，CI 仍然报不一致怎么办？

比较 CI 使用的 Go 版本、工作目录和提交中的 go.mod、go.sum、vendor/modules.txt。确认生成 vendor 的文件已经提交，并在 CI 中显式使用 -mod=vendor，不要依赖本机的 GOFLAGS。