Go vendor 为什么构建时找不到模块

Go 项目明明有 vendor 目录，执行 go build 却仍然提示找不到模块，通常不是“vendor 没生效”这么简单。最常见的原因有四类：命令不在主模块根目录执行、go.mod 的 go 版本不满足自动 vendoring 条件、vendor/modules.txt 和 go.mod 已经不一致，或者这个依赖根本没有被 go mod vendor 收集进去。

我的处理习惯是先确认“当前构建使用谁作为主模块”，再决定是否重建 vendor，最后才选择 -mod 模式。这样不会把一个清单问题误判成网络问题。

官方参考：https://go.dev/ref/mod、https://pkg.go.dev/cmd/go

先确认 vendor 是否真的会参与构建

Go 的 vendor 不是任意目录都能被识别。模块模式下，只有主模块根目录下的 vendor 才有机会被使用；子目录、某个依赖模块内部的 vendor，不能替代主模块的 vendor。先把命令放在含有 go.mod 的项目根目录，再查看 Go 实际识别到的模块文件。

# 在项目根目录确认主模块和 Go 工具链信息
pwd
go env GOMOD
go version

# 查看项目是否存在 vendor 清单
test -f go.mod && echo "已找到 go.mod"
test -f vendor/modules.txt && echo "已找到 vendor/modules.txt"

如果 go env GOMOD 指向的不是当前项目，先修正工作目录；如果返回空值，说明当前命令没有处在 module-aware 项目里。仅仅把一个旧的 vendor 文件夹复制到当前目录，并不能让它变成有效依赖源。

检查 go.mod 与 vendor/modules.txt 是否同一份依赖图

当 go.mod 中的 go 指令为 1.14 或更高，并且主模块根目录存在一致的 vendor/modules.txt 时，构建命令可以自动按 vendor 模式加载依赖。显式写 -mod=vendor 时，Go 不访问网络或模块缓存，而是直接从 vendor 目录读取。

关键点在“一致”。go mod vendor 会根据主模块依赖图重建 vendor，并生成列出模块版本和包的 vendor/modules.txt。如果你刚执行过 go get、手工修改了 go.mod，或切换分支后没有重新生成清单，构建就可能报告 vendoring 不一致，表现为某个模块或包找不到。

# 先让模块依赖描述回到当前源码需要的状态
go mod tidy

# 再按 go.mod 重新生成 vendor 和 modules.txt
go mod vendor

# 明确要求构建只从 vendor 读取依赖
go build -mod=vendor ./...

这里的修复顺序很重要：go mod tidy 负责整理依赖图，go mod vendor 负责把依赖图 materialize 到 vendor。只运行后一个命令，无法替你补全源码实际引用但尚未进入 go.mod 的依赖。

依赖仍找不到时，排查这三个边界

1. 依赖只出现在测试或特定构建条件中

go mod vendor 收集的是主模块构建和测试所需的包，构建约束、测试位置和实际导入路径都会影响结果。先确认报错的导入路径是否真的出现在当前模块的源码或测试里，再确认它对应的模块是否在 go.mod 中。

# 列出主模块包，帮助定位实际参与加载的导入路径
go list ./...

# 查看某个包为什么出现在依赖图中；替换成实际导入路径
go mod why example.com/your/module/package

如果这个包只在另一个模块、被忽略的文件或未启用的构建标签中出现，直接复制它的目录到 vendor 并不能形成可靠修复；应让依赖声明和构建条件保持一致。

2. replace 指向本地路径，但 vendor 只保留了可发布依赖

开发阶段常见的 replace example.com/common => ../common 会改变模块解析来源。此时先确认 replace 的本地路径存在，并理解交付环境是否还能访问它。要做真正离线、单目录构建，应把依赖关系整理成适合发布的模块结构，再重新生成 vendor，不要把宿主机绝对路径当成部署方案。

3. 你需要的是联网修复，而不是离线构建

三种模式的职责不同：

如果 vendor 已经落后于依赖图，临时用 -mod=mod 只能帮助你确认远端或缓存中是否有该模块，不能替代最终的 vendor 更新。反过来，如果交付要求完全离线，使用 -mod=mod 会把问题推迟到没有网络的环境。

我会保留的最小检查清单

1. 命令在主模块根目录执行，go env GOMOD 指向预期的 go.mod。
2. vendor 和 vendor/modules.txt 与当前分支的 go.mod 同步生成。
3. 报错导入路径属于当前主模块真正需要的源码或测试，不是复制来的无效目录。
4. 交付环境明确选择 -mod=vendor、-mod=mod 或 -mod=readonly，不要依赖开发机默认值。
5. 不要手改 vendor 中的第三方包；依赖变化后重新运行 go mod vendor。

归根结底，Go vendor 不是“把依赖文件夹放进项目”这么简单，而是 go.mod 依赖图、vendor/modules.txt 版本清单和构建模式三者共同决定的解析结果。先找主模块，再更新清单，最后选择模式，通常就能把“找不到模块”收敛到一个明确的故障边界。

常见问题

为什么有 vendor 目录还会访问网络？

可能是 Go 版本条件不满足自动 vendoring、vendor 不在主模块根目录，或者命令显式使用了 -mod=mod。需要按上面的主模块和模式检查顺序排除。

vendor/modules.txt 可以手工修改吗？

不建议。它是由 go mod vendor 根据依赖图生成的清单；手工修改容易让版本记录与实际目录脱节，依赖变化时应重新生成。