Go vendor 模式下依赖构建的切换方法

Go 项目里的依赖来源可以明确切换：要让构建读取仓库内的 vendor，使用 -mod=vendor；要临时回到模块缓存，使用 -mod=mod；只想禁止自动修改 go.mod，可以使用 -mod=readonly。如果主模块的 go.mod 中声明的 Go 版本不低于 1.14，且项目根目录存在一致的 vendor，许多构建命令会自动采用 vendor 模式。

真正容易出问题的地方不是参数本身，而是“本地默认行为”和“CI 显式行为”不一致：开发机可能读到了旧的 vendor，CI 却从模块缓存下载了新版本。下面按生产构建的顺序，把依赖同步、切换方式和发布检查拆开说明。

官方文档：https://go.dev/ref/mod

一、先确认 vendor 的自动启用条件

自动模式由三个条件共同决定：当前命令处在主模块中，主模块根目录存在 vendor 目录，go.mod 的 go 指令至少为 1.14。此外，启用 vendor 时，Go 会读取 vendor/modules.txt，并检查它记录的模块版本是否与 go.mod 一致。

可以把项目结构理解成下面这样：

module example.com/orders

// Go 1.14 及以上且根目录有 vendor 时，构建可能自动使用 vendor。
go 1.23

require example.com/codec v1.4.0

对应的文件位置必须是主模块根目录下的 vendor/modules.txt，而不是某个子包自己的 vendor。子目录里的 vendor 不会替代主模块根目录的 vendor。

二、先用 go mod vendor 同步依赖副本

依赖版本发生变化后，不要只提交 go.mod 和 go.sum，还要重新生成 vendor。go mod vendor 会按照主模块当前需要构建和测试的包，把依赖复制到根目录 vendor，同时生成 vendor/modules.txt。

# 根据 go.mod、go.sum 和源码重新生成 vendor 副本与模块清单
go mod vendor

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

如果只改了 go.mod，没有重新执行 go mod vendor，构建可能报出 vendor 清单不一致。这里的修复不是手工编辑 vendor/modules.txt，而是回到依赖解析结果重新生成整个 vendor 目录。

需要注意，go mod tidy、go mod download 和 go get 的职责仍然是维护模块图或模块缓存；即使当前构建采用 vendor，它们也不等于“只在 vendor 内工作”。依赖更新阶段可以联网，正式构建阶段再固定使用已提交的 vendor。

三、按场景切换 -mod 参数

三种模式的差异可以用“依赖从哪里来”和“是否允许改 go.mod”两个问题来判断：

例如，本地需要比较模块缓存中的版本，而不想删除仓库里的 vendor，可以临时这样执行：

# 临时忽略 vendor，使用模块缓存；该命令不会把 vendor 更新成新版本
go test -mod=mod ./...

# 使用 go.mod 和模块缓存，但发现需要修改 go.mod 时直接报错
go list -mod=readonly ./...

不要把 -mod=mod 当成“修复 vendor”的参数。它只是切换依赖来源；修复仓库副本仍然应该先完成依赖变更，再执行 go mod vendor。

四、把 CI 的依赖更新和构建权限分开

企业项目最稳妥的做法是分成两个职责不同的阶段：依赖维护任务可以使用 -mod=mod 或 go get 更新模块，审阅变更后提交 go.mod、go.sum、vendor 和 vendor/modules.txt；普通 CI 只使用提交后的 vendor 构建，不在构建过程中联网补依赖。

# 依赖维护阶段：允许解析模块并重新生成仓库副本
go get example.com/codec@v1.4.0
go mod tidy
go mod vendor

# 普通 CI 阶段：固定从已提交的 vendor 构建和测试
go build -mod=vendor ./...
go test -mod=vendor ./...

如果希望所有接受该参数的 Go 命令都默认使用 vendor，也可以在 CI 环境里设置：

# 只在当前 CI 任务内固定依赖来源，避免影响开发机的全局配置
export GOFLAGS=-mod=vendor
go test ./...

命令行显式的 -mod=mod 或 -mod=readonly 可以覆盖这个默认值。这样做的价值是把“是否允许访问模块代理”变成构建脚本中可见的配置，而不是依赖不同机器的默认状态。

五、发布前的 vendor 一致性清单

发布前可以按下面的顺序检查文件和参数，重点是确认提交内容足以支撑构建：

1. 确认根目录：go.mod、vendor/ 和 vendor/modules.txt 位于同一个主模块根目录。
2. 确认更新顺序：依赖变更完成后重新运行 go mod vendor，不要手工修改清单。
3. 确认构建参数：正式构建和测试显式使用 -mod=vendor，或在 CI 内固定 GOFLAGS。
4. 确认网络边界：构建阶段不依赖临时下载；需要更新依赖时走单独的维护任务。
5. 确认提交完整：把代码、go.mod、go.sum、vendor 和清单作为同一变更审阅。

如果团队暂时不提交 vendor，也要在 CI 中明确使用 -mod=mod 或 -mod=readonly，并接受构建依赖模块缓存或代理。最需要避免的是“有 vendor 但没有约定”：有人读仓库副本，有人读缓存，最终同一提交在不同环境产生不同依赖来源。

常见问题

有 vendor 目录时，为什么还要写 -mod=vendor？

Go 1.14 及以上通常会根据 go.mod 的版本和根目录 vendor 自动启用，但在 CI 中显式写出参数更容易审阅，也能避免环境变量或工具链差异造成误判。

vendor/modules.txt 不一致怎么办？

重新确认 go.mod 的依赖变更，再执行 go mod vendor，然后把生成结果与模块文件一起提交。不要只改清单里的版本行。

如何临时不使用 vendor？

对支持该参数的构建命令使用 -mod=mod；如果只想禁止修改 go.mod，使用 -mod=readonly。这两者都不会更新仓库里的 vendor。

总结

Go vendor 模式的关键不是“目录是否存在”，而是依赖清单、主模块版本和构建参数是否统一。用 go mod vendor 生成一致副本，用 -mod=vendor 固定正式构建，用 -mod=mod 管理依赖更新，用 -mod=readonly 做只读模块检查，就能把本地与 CI 的依赖来源切换变成可审阅的工程约定。