Go mod vendor 后构建结果为什么不同

我遇到过一种很容易误判的构建差异：同一个提交，在开发机上执行 go mod vendor 之后可以通过，CI 却编译出了不同结果，甚至报“找不到包”或出现不同的依赖版本。通常不是 vendor 目录自己改变了业务代码，而是两边没有使用同一套依赖来源。

先确认构建模式，再检查 vendor/modules.txt 是否和 go.mod 同步，最后核对 go 指令、Go 工具链和 go.work。这三个层面中任意一个不同，构建结果就可能不同。

下面的排查只围绕 vendor 目录、Go 版本和依赖选择展开。

先确认构建到底用了哪份依赖

go mod vendor 会根据主模块当前的依赖图重建根目录下的 vendor，同时生成 vendor/modules.txt。但“目录存在”不等于每一次构建都在使用它。

显式的 -mod=vendor 会要求 Go 从主模块的顶层 vendor 目录满足依赖；-mod=mod 则把判断切回模块文件和模块缓存。对于满足条件的较新模块，go 指令还可能自动选择 vendor 模式。先把两种来源分开比较：

# 查看当前模块、工作区、全局构建参数和 Go 工具链
go env GOMOD GOWORK GOFLAGS GOVERSION

# 明确使用 vendor 目录构建，便于和 CI 的参数对照
go build -mod=vendor ./...

# 明确使用模块文件与模块缓存构建，不读取主模块 vendor 目录
go build -mod=mod ./...

如果第一条成功、第二条失败，差异来自依赖来源或模块缓存，而不是编译器随机行为；如果两条都成功但产物不同，就继续检查下面的版本和 replacement。

再检查 vendor/modules.txt 与 go.mod

vendor/modules.txt 不只是文件清单，它还携带被复制依赖的模块版本信息。Go 在 vendor 模式下会用它提供模块版本，并检查它和 go.mod 是否一致。只改了 go.mod 却没有重新生成 vendor，就可能得到“本地能用、CI 不同”的结果。

# 先查看主模块声明的依赖、替换关系和 Go 指令
sed -n '1,220p' go.mod

# 查看 vendor 清单里的模块版本和显式依赖标记
sed -n '1,220p' vendor/modules.txt

# 依赖声明变更后，在主模块根目录重新生成 vendor
go mod vendor

# 检查生成后的目录是否出现待提交变化
git diff -- go.mod go.sum vendor/modules.txt

常见的失配有三种：一是 require 的版本变了，二是 replace 指向了不同位置，三是清单来自另一个工作区或另一个提交。Go 官方文档也明确说明，go mod vendor 会先重建已有 vendor 目录，因此不要直接在 vendor 包里手工修补代码。

如果项目使用了本地替换，务必把它当成构建输入的一部分：

module example.com/service

go 1.21

require example.com/contracts v0.4.0

// 中文注释：本地联调时替换为工作区旁的模块；CI 若没有同一路径，就不能得到相同输入。
replace example.com/contracts => ../contracts

这种 replacement 如果只存在于开发机上的未提交修改，执行 vendor 后复制进去的内容也会和 CI 不同。要么提交一致的替换结果，要么在 CI 使用同样的模块布局，不要把 vendor 当成自动修复工具。

Go 指令和 go.work 也会改变选择

很多排查只盯着本机执行的 Go 版本，却忽略了主模块 go.mod 中的 go 指令。它不只是文档备注：从 go 1.14 起，当 vendor 清单存在且与 go.mod 一致时，Go 可以自动启用 vendor 模式；低于这个门槛或清单不适配时，默认选择可能不同。

在更高版本的模块语义中，go mod vendor 还会把依赖自身的 Go 版本写入清单，并按模块图记录显式依赖。于是“同一份源码、不同 Go 工具链”可能在清单生成、依赖图解释或默认构建模式上出现差异。

如果目录中存在 go.work，还要确认命令是否在工作区模式运行。工作区可能把多个主模块组合起来，生成的 vendor 清单也必须和实际运行模式匹配：

# 输出当前命令真正读取的模块文件和工作区文件
go env GOMOD GOWORK

# 直接查看工作区包含哪些模块，避免把 go.work 的输入漏算
go work edit -json

# 在项目根目录生成 vendor，并显式指定构建模式做对照
go mod vendor
go build -mod=vendor ./...

开发机在父目录发现了 go.work，而 CI 只检出单个模块时，两边的主模块集合就可能不同。此时先决定项目到底采用单模块还是工作区构建，再把选择写进脚本和文档。

把构建来源固定下来

定位完差异后，推荐把构建契约收敛成一套明确输入：

• 依赖声明变化后，在主模块根目录重新运行 go mod vendor，提交 vendor 与 vendor/modules.txt 的变化。
• 本地和 CI 使用相同的 Go 工具链，并把 go.mod 的 go 指令视为构建语义的一部分。
• 需要离线或严格复现时，显式使用 go build -mod=vendor ./...；不想依赖 vendor 时，显式使用 -mod=mod，不要让环境变量决定结果。
• 如果使用 go.work，把工作区文件纳入构建输入，或在 CI 中明确禁用它，避免“本机自动发现、CI 没有发现”的差异。

最后再执行一次对照，重点不是比较日志长短，而是确认两边的 GOMOD、GOWORK、GOFLAGS、Go 版本和 vendor 清单来自同一个提交。这样 go mod vendor 就只是依赖快照生成动作，而不会继续成为构建结果差异的隐藏来源。

相关问题

vendor 目录提交后还能修改里面的依赖代码吗？

不建议。下次运行 go mod vendor 会重建目录并覆盖手工修改；应修改上游模块、使用明确的 replacement，或提交真正可复现的模块版本。

为什么加了 vendor 目录，Go 还是访问模块代理？

可能没有启用 vendor 模式、清单与 go.mod 不一致，或者命令运行在不同工作区。先用 go env 和显式的 -mod=vendor、-mod=mod 做对照。