Go Go modules vendor 只读构建环境如何强制使用 vendor

在只读 CI、内网构建机或没有模块缓存的环境里，最稳妥的做法不是只加 -mod=readonly，而是明确使用 -mod=vendor。前者只表示“不要改写 go.mod”，后者才表示“依赖从主模块顶层 vendor 目录读取”。如果还要把网络作为故障兜底关掉，可以叠加 GOPROXY=off。

只读构建为什么还要明确依赖来源

Go 1.14 及更高版本中，如果主模块的 go.mod 声明版本不低于 1.14，根目录又存在与 go.mod 一致的 vendor/modules.txt，许多构建命令会自动进入 vendor 模式。但把“默认行为”当成 CI 契约仍然有风险：构建镜像可能换了 Go 版本，仓库可能把 vendor 放在子目录，或者依赖更新后忘记重新生成清单。

显式写出 -mod=vendor 的价值，是把依赖树固定在仓库里。构建命令不会去网络或本地模块缓存寻找外部模块；如果 vendor 缺包，构建直接失败，问题会留在依赖同步阶段，而不是悄悄变成一次不可复现的下载。

用 -mod=vendor 把构建锁在 vendor

单次验证可以直接把标志写在命令上。下面的组合适合在已经提交 vendor 的仓库中执行；注释说明的是配置意图，不是运行输出。

# 强制 go test 只从主模块 vendor 目录解析依赖
GOPROXY=off go test -mod=vendor ./...

# 构建命令同样不读取网络或本地模块缓存
GOPROXY=off go build -mod=vendor ./...

如果项目里有多个脚本，推荐在 CI 作业级别设置 GOFLAGS，避免某个脚本漏写参数：

# 让接受 -mod 标志的 Go 命令默认使用 vendor
export GOFLAGS="-mod=vendor"

# GOPROXY=off 把缺失依赖暴露为失败，不允许网络兜底
export GOPROXY=off

# 这里不需要再重复写 -mod=vendor
go test ./...
go build -trimpath ./cmd/server

GOFLAGS 是命令行参数的默认集合，显式命令行参数可以覆盖同名设置。若某个维护脚本必须执行 go mod tidy、go mod download 或 go get，不要把它和生产构建混在同一个只读阶段：这些模块管理命令的职责是更新或下载依赖，不能用来证明构建使用了 vendor。

-mod=vendor、-mod=readonly 和 GOPROXY=off 怎么区分

因此，“只读”至少要拆成两个问题：依赖从哪里读取，以及构建过程能不能改模块文件。需要 vendor 时使用 -mod=vendor；需要阻断网络时再加 GOPROXY=off。把 -mod=readonly 写成唯一参数，反而会让命令绕过 vendor。

vendor 不一致时报错，应该回到可写环境修复

当 go.mod 改过但 vendor 没同步，Go 会报告 inconsistent vendoring，常见原因包括显式 require 没有在 vendor/modules.txt 中标记、版本不一致，或者 vendor 目录缺少构建所需包。这不是 CI 应该自行“修好”的错误，因为修复会改变提交物。

# 仅在依赖维护分支的可写环境执行，重新整理模块清单
go mod tidy
go mod vendor

# 提交以下三类变更，供只读构建消费
git add go.mod go.sum vendor

回到 CI 后，用 GOPROXY=off GOFLAGS=-mod=vendor go test ./... 复查。若提示找不到包，先检查它是否真的属于主模块构建需要的依赖、是否已被 go mod vendor 收集，以及仓库根目录是否就是包含 go.mod 的主模块根。不要把一个临时生成的空 vendor 目录提交进去，它只会把真正的依赖缺失推迟到更难排查的位置。

一份适合 CI 的最小检查清单

• 构建工作目录指向包含 go.mod 的主模块根目录。
• 仓库提交了 vendor/ 和 vendor/modules.txt，不是只提交 go.mod。
• 构建阶段使用 GOFLAGS=-mod=vendor，隔离环境再使用 GOPROXY=off。
• 依赖升级只在可写维护阶段完成，然后重新生成 vendor 并提交变更。
• 不要把 -mod=readonly 当成 vendor 开关；它表达的是禁止修改 go.mod。

相关问题

go.mod 写的是 1.14 以上，还需要手动写 -mod=vendor 吗？

如果根目录的 vendor 和 vendor/modules.txt 与 go.mod 一致，Go 通常会自动使用 vendor。CI 仍建议显式设置，因为这样不依赖构建机对默认行为的猜测，也能让配置意图一眼可见。

使用 -mod=vendor 后能不能再执行 go mod tidy？

不建议把两者放在只读构建阶段。go mod tidy 是依赖维护命令，可能需要访问模块来源并修改 go.mod；它应在可写环境运行，构建阶段只消费已同步的提交物。