Go vendor 模式下新增依赖为什么没有被编译器采用

项目已经执行过 go get，go.mod 里也出现了新模块，但构建时仍提示找不到导入包，这通常不是编译器拒绝了新依赖，而是 Go 命令被固定在 -mod=vendor，只会查看主模块顶层的 vendor。改动 go.mod 不会自动复制第三方源码；在模块根目录重新执行 go mod vendor，让 vendor/modules.txt 和 vendor 包目录一起更新，问题一般就能解决。

先确认导入路径确实属于新模块，再用 go mod vendor 重建 vendor，最后用同一个 -mod=vendor 检查 go list、go test 和 go build。不要只看模块缓存里有没有源码。

先判断：到底是谁在解析依赖

这里先别急着删目录或修改环境变量。Go 编译器本身只接收已经解析好的包源码，真正决定“从哪里找包”的是 go 命令。主模块的 go.mod 使用较新的模块模式并且根目录有 vendor 时，构建命令可能默认采用 vendor；显式写出 -mod=vendor 则能把排查边界固定下来。

从项目根目录检查当前模式：

# 进入包含 go.mod 的主模块根目录
cd /path/to/your-module

# 显式固定为 vendor 解析，避免把模块缓存结果当成结论
go list -mod=vendor -m all

# 查看 Go 命令的全局构建参数；若包含 -mod=vendor，要纳入排查
go env GOFLAGS

如果错误类似“cannot find module providing package …: import lookup disabled by -mod=vendor”，它已经说明网络和模块缓存没有参与这次解析。此时重点是补齐 vendor，而不是继续下载同一个模块。

新增依赖为什么不会自动出现在 vendor 目录

go get 解决的是“模块依赖描述如何变化”，而 go mod vendor 解决的是“主模块构建和测试需要哪些源码应该复制到 vendor”。两者目标不同，所以只看到 go.mod 发生变化，并不能证明构建使用的本地依赖树已经变化。

推荐按下面的顺序更新。命令中的注释说明了每一步的目的：

# 在模块根目录加入目标模块；版本按项目实际需要填写
go get example.com/clockwork@v1.4.0

# 根据 import、go.mod 和测试依赖整理 go.mod/go.sum
go mod tidy

# 重新生成顶层 vendor 与 vendor/modules.txt
go mod vendor

# 用 vendor 模式查询目标包最终来自哪里
go list -mod=vendor -f '{{.ImportPath}} -> {{.Dir}}' example.com/clockwork

最后一条命令的目录应落在当前模块的 vendor/example.com/clockwork 之下。若仍然没有对应包，先检查代码中的 import 是否真的使用了该模块提供的包路径；仅在 require 中写入一个模块，并不会让所有模块源码都进入 vendor。

也不要直接编辑 vendor/modules.txt。它是 go mod vendor 根据依赖图生成的清单，手工改一行可能暂时绕过某个提示，却会让清单版本和实际源码继续失配。

哪些情况会让“已经 vendor”看起来仍然不生效

第一种是目录层级错了。Go 使用的是主模块根目录的顶层 vendor，把依赖放进某个子目录的 vendor，或者在多模块仓库的另一个模块根目录执行命令，都不能替代当前主模块的 vendor。

第二种是 import 路径和模块路径混淆。例如模块路径是 example.com/clockwork，代码却导入了它仓库里的另一条目录路径；这时即使 vendor 中有源码，也不是同一个包。用 go list -m -json all 查看模块版本，用 go list -mod=vendor 查看具体包目录，能把两个层次分开。

第三种是构建条件。go mod vendor 会按主模块代码和测试依赖整理需要的包，但特定文件可能受 GOOS、GOARCH 或 build tag 影响。排查时要用和生产相同的环境与标签，不要只在默认平台上运行一次就下结论。

# 使用生产目标平台和标签查询同一导入路径
GOOS=linux GOARCH=amd64 go list -mod=vendor -tags=prod -f '{{.ImportPath}} -> {{.Dir}}' example.com/clockwork

# 只比较清单是否能被当前 go.mod 接受，不要手工修改 modules.txt
GOOS=linux GOARCH=amd64 go test -mod=vendor ./...

如何确认编译器看到的是哪一份依赖

复查要保持同一个解析模式。先让 go list 给出包目录，再让测试和构建使用相同的 -mod=vendor。这样看到的路径、测试输入和最终编译输入才属于同一套依赖边界。

# 先确认包目录落在顶层 vendor，而不是模块缓存
go list -mod=vendor -f '{{.Dir}}' example.com/clockwork

# 测试和构建沿用同一个依赖解析边界
go test -mod=vendor ./...
go build -mod=vendor ./...

如果 go list 输出的是 $GOMODCACHE，说明本次命令没有使用 vendor；如果输出位于项目根目录的 vendor，才与生产的离线构建假设一致。出现 inconsistent vendoring 时，通常应回到 go mod tidy 和 go mod vendor 重新生成，而不是换一个模块缓存版本。

可以把最终检查固化到发布脚本中：

# 发布前只接受 vendor 模式下能解析并构建的依赖树
set -e
go list -mod=vendor ./...
go test -mod=vendor ./...
go build -mod=vendor ./...

这样做的重点不是强迫所有项目永久使用 vendor，而是让“构建依赖来自哪里”成为明确、可重复的工程约束。若项目决定回到模块缓存，就应统一使用 -mod=mod 或默认模块模式，并同步调整离线构建假设。

相关问题

只执行 go mod tidy，为什么 vendor 还是旧的？

go mod tidy 主要整理 go.mod 和 go.sum，不会代替 go mod vendor 重建源码目录。依赖描述变化后，仍需在模块根目录执行后者。

go get 能不能直接加上 -mod=vendor？

不能把两者当作同一个动作。go get 的职责是修改依赖，而 vendor 模式是构建时的解析边界；先更新依赖，再生成 vendor，最后用 -mod=vendor 构建。

vendor 目录存在时还需要显式写 -mod=vendor 吗？

当 go.mod 的 go 指令和 vendor 清单满足默认条件时，部分构建命令会自动采用 vendor。发布脚本显式写出该参数更容易复查，也能避免不同 Go 版本的默认行为造成误判。