Go vendor 目录什么时候会被 go 命令自动启用

Go 项目里出现 vendor 目录，并不等于每次运行 go build 都会自动从里面取依赖。模块模式下，先看 go.mod 的 go 行：当它是 1.14 或更高版本，且项目根目录有 vendor 目录时，许多加载模块的命令默认会按 -mod=vendor 处理；与此同时，vendor/modules.txt 还要和 go.mod 的依赖信息一致。

最稳妥的判断顺序是：确认模块模式和 go 行，检查 vendor/modules.txt，再查看 GOFLAGS 或命令行上的 -mod 是否覆盖默认值。目录存在但清单过期，仍可能得到“inconsistent vendoring”错误。

自动读取 vendor 目录要满足哪些条件

先把问题拆成三个独立条件。第一，工程要处于模块感知模式，根目录能找到 go.mod；第二，go.mod 的 go 行至少是 1.14；第三，根目录下确实有由 go mod vendor 维护的 vendor 树。三个条件缺一个，都不要把“目录存在”当成默认行为。

// 这不是业务代码，而是一个最小 go.mod 片段。
module example.com/report

go 1.22

require example.com/codec v1.4.0

这里的 go 1.22 描述模块期望的语言和模块语义，不是单纯记录开发机版本。达到阈值后，go build、go test、go list 等需要加载包的命令，才可能根据 vendor 快照取依赖；而 go mod tidy、go mod vendor 这类维护依赖图的命令，不应简单理解为“读取 vendor 后再工作”。

为什么 vendor/modules.txt 比目录本身更关键

go mod vendor 不只复制源码，还会生成 vendor/modules.txt。这个文件记录被 vendored 的模块及其版本，Go 命令在使用 vendor 模式时会拿它和 go.mod 对照。因而常见的失败不是“找不到 vendor”，而是分支切换后 go.mod 更新了，vendor 树却没有重新生成。

# 在模块根目录重新生成依赖快照。
go mod vendor

# 查看 Go 实际识别到的模块文件和全局参数。
go env GOMOD GOFLAGS

如果构建报 inconsistent vendoring，先不要删目录或盲目下载依赖。通常应检查最近一次修改是否只提交了 go.mod、是否漏提交 vendor/modules.txt，以及生成 vendor 时使用的 Go 工具链是否与 CI 约定一致。重新执行 go mod vendor 后，把变更作为同一个提交审阅。

默认模式和显式 -mod 怎么分工

自动启用只是默认值，命令行参数和 GOFLAGS 可以把它改掉。-mod=vendor 强制从 vendor 读取，并且不使用网络或模块缓存；-mod=mod 则回到模块缓存或代理解析依赖，必要时允许更新 go.mod 和 go.sum；-mod=readonly 更适合不允许改动依赖文件的构建环境。

# CI 明确要求只使用已提交的 vendor 快照。
go build -mod=vendor ./...

# 临时比较模块缓存路径，但不要把这个参数悄悄写进长期脚本。
go list -mod=mod -m all

实际排查时，先看命令本身有没有 -mod，再看 GOFLAGS。两处都没有覆盖，才回到 go.mod 的 go 行和 vendor 目录判断默认模式。还要留意 go get 的职责是修改依赖，它不能把 vendor 模式当作普通构建开关使用；生成依赖快照与消费依赖快照是两条不同的工作流。

提交和部署前的 vendor 检查清单

• 构建目录是否真的是包含目标 go.mod 的模块根目录或其子目录。
• go.mod、go.sum、vendor/ 和 vendor/modules.txt 是否作为同一组变更提交。
• CI 是否固定 Go 工具链，并明确使用 -mod=vendor、-mod=readonly 或默认值。
• 是否把 GOFLAGS 写进构建日志，避免本地和 CI 只因环境变量不同而读取不同依赖。

相关问题

只有 vendor 目录，没有 vendor/modules.txt，可以自动启用吗？

不要这样假设。自动模式依赖 Go 对 vendor 快照的识别和一致性检查，应该在模块根目录执行 go mod vendor，把清单一并提交。

怎么强制 Go 不使用 vendor？

对支持该参数的模块加载命令使用 -mod=mod，并检查 GOFLAGS 没有重新写回 -mod=vendor。这是排查“vendor 内容与缓存内容不同”的临时对照手段。

为什么本地能编译，CI 却报 inconsistent vendoring？

优先比较两边的 go.mod、vendor/modules.txt、Go 工具链和 GOFLAGS。最常见的原因是依赖文件已更新但 vendor 快照没有同步生成，或 CI 使用了另一套分支内容。