Go modules replace判断 vendor 与 module 模式的迁移清单

我在把一个依赖本地 fork 的 Go 服务交给 CI 构建时，最容易误判的一点是：replace 和 vendor 都能“让代码编译通过”，但它们解决的不是同一个问题。replace 改变当前主模块的依赖来源，vendor 则把解析后的依赖复制进主模块目录。迁移时先确认解析来源，再生成并校对 vendor/modules.txt，最后统一构建参数，通常比直接删除 replace 稳妥。

先把 replace 与 vendor 的边界画清楚

replace 更像开发期的“解析重定向”：导入路径可以保持不变，Go 命令从本地目录或另一个模块版本取源码。它只影响当前主模块，发布一个依赖你的下游模块时，不能指望下游自动继承这条替换规则。更关键的是，单独写 replace 不会把模块放进模块图，通常还要有匹配的 require。

vendor 是交付期的“源码快照”：依赖包被放到主模块根目录下，构建时可以从这棵目录读取。对于 go.mod 中 Go 版本为 1.14 或更高、且主模块根目录存在 vendor 的项目，Go 命令可能自动采用 vendor 模式；为了让 CI 行为明确，我更愿意在构建脚本中显式写出 -mod=vendor。

第一步：检查 replace 真正指向了哪里

不要只打开 go.mod 看一眼。先记录模块声明、Go 版本、对应的 require 和 replace 目标，再用模块查询确认实际目录。下面的命令只读取解析结果，不修改依赖：

# 查看主模块、依赖版本与实际源码目录
go list -m -json all

# 只看目标模块的路径、版本和本地目录
go list -m -f '{{.Path}} {{.Version}} {{.Dir}}' example.com/acme/codec

# 检查当前模块是否声明了替换规则
go mod edit -json

如果 Dir 落在本地 fork 目录，说明当前仍是 replace 驱动；如果切换到 vendor 后，目录来自主模块的 vendor 子树，才算完成了来源切换。这里不要把“能找到包”误认为“使用了 vendor”。

第二步：生成 vendor 并校对模块清单

确认本地 fork 已经可以作为最终源码后，在主模块根目录生成 vendor：

# 按当前 go.mod、go.sum 和 replace 解析结果复制构建所需依赖
go mod vendor

# 检查 vendor 清单中是否出现目标模块与版本
grep -n "example.com/acme/codec" vendor/modules.txt

# 查看待提交文件，确认 replace、go.sum 与 vendor 一起变化
git status --short

vendor/modules.txt 不是可有可无的索引文件。Go 命令会用它记录 vendor 中的模块版本，并在它与 go.mod 不一致时报告错误。以后只要修改了 require、replace 目标或模块版本，就要重新运行 go mod vendor，不能手工编辑清单凑结果。

迁移前后建议把“源码来源”当成一组关系检查：replace 指向的模块、vendor 中的模块、代码实际导入的包，三者要能闭合。下面这张结构图把这三个对象与构建参数放在同一边界里，便于排查漏提交。

第三步：区分 module 模式和 vendor 模式

我通常先在本地用 -mod=vendor 做构建和测试，再让 CI 明确使用同样的参数；依赖整理命令仍单独在模块模式下执行。这样既能让发布构建不依赖网络，也不会错误地认为 vendor 会改变所有 go mod 命令的行为。

迁移清单：什么时候可以删掉 replace

1. 来源确认：本地 fork 的修改已经合并到可交付的模块版本，或决定把 fork 的代码正式纳入 vendor。
2. 模块确认：require 仍指向代码实际使用的模块路径，不能只删 replace 而留下一个无法下载的版本。
3. 清单确认：重新执行 go mod vendor，检查 vendor/modules.txt 与 go.mod 一致。
4. 入口确认：开发、测试、CI 和发布脚本对 -mod=vendor 或 -mod=mod 的选择一致。
5. 回退确认：把“恢复 replace、删除 vendor、重新生成 vendor”写成一个可回滚提交，不在失败时临时改目录。

如果 fork 仍在快速迭代，或者不同服务必须使用不同修复版本，先保留 replace 更合适；如果目标是可重复的离线构建和审计依赖来源，vendor 才更有价值。两者也可以短期并存，但要把谁是正式构建入口写进脚本和文档。

常见问题

只执行 go mod vendor 就能删除 replace 吗？

不能。先确认 vendor 已包含正确的替换源码，并决定后续构建是否固定使用 vendor；否则删除 replace 后，模块解析可能回到缓存或网络版本。

vendor/modules.txt 为什么总是提示不一致？

通常是 go.mod 的 require、Go 版本或 replace 发生变化后没有重新生成 vendor。回到主模块根目录执行 go mod vendor，再把成套文件提交。

启用 vendor 后 go mod tidy 也不走 vendor 吗？

不会。vendor 主要影响构建和测试加载包的来源，go mod tidy、go mod download 等模块命令仍按模块图工作，不能用一次构建成功替代依赖整理。

判断这次迁移是否完成，可以只问三个问题：构建实际读的是哪棵目录、vendor/modules.txt 是否与模块声明一致、所有入口是否使用同一模式。三项都能回答清楚，再删除 replace 才不会把一次本地调试改成 CI 随机取依赖。