Go 模块vendor 模式没有使用 vendor 目录怎么办

如果 Go 项目已经有 vendor 目录，但构建仍然下载依赖，先不要急着删除缓存。Go 只会把主模块根目录下的 vendor 当作候选，而且自动启用还受 go.mod 中的 go 版本和 -mod 参数影响。最短排查路径是：确认 go env GOMOD 找到的主模块，再看 go env GOFLAGS 是否强制了 -mod=mod 或 -mod=readonly，最后重新生成 vendor/modules.txt。

想让构建明确使用 vendor，可以在主模块根目录执行 go build -mod=vendor ./...。如果这个命令仍失败，优先处理目录层级、工作区模式或 vendor 清单不一致，而不是继续重试普通的 go build。

• 位置：只能使用当前主模块根目录的顶层 vendor，子模块或父目录里的同名目录不算。
• 版本：go.mod 的 go 行达到 1.14 时，完整且一致的 vendor 才可能自动启用。
• 覆盖：显式 -mod=mod、-mod=readonly 或对应的 GOFLAGS 会关闭 vendor。
• 清单：vendor/modules.txt 必须由当前 go.mod 和源码状态重新生成并保持一致。

先确认当前命令到底在哪个模块里

很多“vendor 没生效”其实是命令执行目录不对。一个仓库可能包含多个模块，或者通过 go.work 组织多个模块；此时你看到的 vendor 目录不一定属于当前命令选中的主模块。下面的命令只读取定位信息，不修改依赖。

# 确认当前命令找到的主模块文件；空值通常表示不在模块上下文中
go env GOMOD

# 确认是否进入了工作区模式；它会影响主模块集合和 vendor 清单
go env GOWORK

# 检查全局是否预置了 -mod=mod 或 -mod=readonly 等覆盖项
go env GOFLAGS

# 查看 Go 工具链版本，避免用旧工具解释新项目配置
go version

如果 GOMOD 指向的文件不是你预期的那一个，先切换到真正的模块根目录再排查。若 GOWORK 返回了一个 go.work 文件，必须确认 vendor 是按当前工作区生成的；单模块模式生成的清单不能直接假设适用于工作区。

vendor 目录需要同时满足哪些条件

把目录命名成 vendor 并不会自动改变依赖解析。Go 官方文档把它定义为主模块根目录中的依赖副本，并用 vendor/modules.txt 保存模块版本和包清单。可先检查这两个位置：

# GOMOD 应该指向当前项目的 go.mod；这里把它的目录作为判断基准
modfile=$(go env GOMOD)
modroot=$(dirname "$modfile")

# 只检查主模块根目录的 vendor，不要误看父目录或子模块目录
test -d "$modroot/vendor" && echo 'vendor 目录存在'
test -f "$modroot/vendor/modules.txt" && echo 'modules.txt 存在'

# 查看当前 go.mod 的 go 行，版本门槛会影响自动 vendoring
grep '^go ' "$modroot/go.mod"

若项目使用 go 1.13 或更低版本，普通构建不会因为目录存在就自动切换到 vendor；可以显式使用 -mod=vendor，也可以在确认兼容性后调整模块的 go 行。若目录是用 go mod vendor -o other-vendor 生成的，它只是给其他工具使用，Go 命令仍只识别主模块根目录中名为 vendor 的目录。

最常见的覆盖项：GOFLAGS 和 -mod

当 go.mod 满足自动条件但依赖仍来自缓存，先查是否有显式模式。命令行参数优先级高于默认判断，GOFLAGS 中的 -mod=mod 也会让 Go 忽略 vendor。可以用一次临时参数区分“目录有问题”和“默认配置被覆盖”：

# 显式要求本次构建只从主模块 vendor 读取依赖
go build -mod=vendor ./...

# 用包目录作为观察点；输出路径包含 vendor 时，说明该包从 vendor 加载
go list -mod=vendor -f '{{.Dir}}' example.com/your-project/internal/app

# 仅本次命令清空 GOFLAGS，避免改动开发机的长期配置
GOFLAGS= go test -mod=vendor ./...

上例中的导入路径要替换成项目真实存在的包。若显式 -mod=vendor 能工作，而不带参数的命令不工作，重点检查 go env GOFLAGS、CI 环境变量和构建脚本。不要把 GOFLAGS=-mod=vendor 无条件写入所有项目：需要下载模块或运行 go mod tidy 时，模块命令并不会因为 vendoring 自动变成离线操作。

重新同步清单，再处理不一致错误

如果明确要提交 vendor，推荐从主模块根目录重新生成，而不是手工复制某个缓存目录。go mod vendor 会按当前 go.mod 和源码需要重建目录，并更新 vendor/modules.txt：

# 在主模块根目录执行，生成与当前依赖图对应的 vendor 副本
go mod vendor

# 先用确定的 vendor 模式编译，错误信息能直接暴露清单或包缺失问题
go test -mod=vendor ./...

# 如果项目只想恢复默认的模块缓存解析，显式使用 mod 模式
go test -mod=mod ./...

出现 inconsistent vendoring 时，通常是 go.mod 已变化但 vendor 没有同步，或者工作区与模块生成的 modules.txt 不匹配。重新执行 go mod vendor 后再检查版本控制差异；若只是临时验证模块缓存，可以使用 -mod=mod，不要把不一致的 vendor 目录继续提交。

按现象选择修复方式

常见问题

vendor 目录放在仓库根目录就一定会被使用吗？

不一定。仓库根目录必须同时是当前主模块根目录；如果真正的 go.mod 在子目录，Go 只看子目录下的顶层 vendor。

为什么 go.mod 有 vendor 目录，仍然访问网络？

先检查 GOFLAGS 或构建脚本是否设置了 -mod=mod，再确认 go 行达到自动 vendoring 的版本要求。还要区分构建命令和 go mod tidy、go mod download 等模块管理命令，后者不会因为 vendor 存在就完全改用本地副本。

直接把缓存目录复制到 vendor 可以吗？

不建议。用 go mod vendor 生成，才能同步包集合、替换关系和 vendor/modules.txt；手工复制容易留下缺包或版本不一致。