Go replace 指向本地目录后 CI 失败的迁移方法

我第一次把一个共享 Go 模块接进业务服务时，为了让本地改动马上生效，在 go.mod 里加了一个指向兄弟目录的 replace。开发机上的测试很顺利，提交到 CI 后却在依赖解析阶段失败。后来我发现，问题不在代码本身，而在“开发机上存在的目录”被误当成了“所有构建环境都能访问的依赖”。

官方地址：https://go.dev/ref/mod

最稳的迁移方式是：本地多模块联调用 go.work，CI 使用仓库里可获取的正式模块版本，并从提交的 go.mod 中移除只对个人目录成立的 replace。如果暂时保留本地替换，至少要确认 CI 的检出布局真的包含目标目录和它的 go.mod。

为什么本机能编译，CI 却找不到模块

Go 官方模块参考把本地目录替换描述为：在主模块的 go.mod 或 workspace 的 go.work 中，用另一个目录的内容替代某个模块。相对路径是相对于包含该文件的模块根目录解析的，而且替换目录本身要能作为模块使用，通常需要有自己的 go.mod。

例如，提交中的模块可能写成下面这样。这个写法本身并不表示“把目录里的源码上传给 CI”，它只是在当前主模块执行命令时改变依赖来源。

module example.com/order

go 1.23

require example.com/shared v0.0.0-replace

// 本地联调时把依赖指向仓库外的兄弟目录。
replace example.com/shared v0.0.0-replace => ../shared

如果 CI 只检出了 order，没有把同级的 shared 一起检出，Go 就无法读取替换目录中的模块文件。另一个常见情况是开发机父目录里有一个未提交的 go.work，本机实际使用的模块集合和 CI 并不相同。两种情况都会造成“本机通过、流水线失败”的错觉。

先确认失败发生在依赖边界

我会先把诊断分成三件事：当前命令是否处在 workspace 模式，提交的 go.mod 是否还带有本地替换，以及模块图最终选择了哪个来源。下面的命令只读取本地配置和模块图，不需要把个人目录写进日志。

# 查看当前 Go 命令是否受某个 go.work 影响。
go env GOWORK

# 查看提交的模块文件里是否仍有本地替换。
go mod edit -json

# 查看模块图中的主模块、版本和替换关系。
go list -m -json all

go env GOWORK 如果返回一个路径，说明当前命令处于 workspace 模式；返回 off 则表示明确关闭了 workspace。查看 go.mod 时，重点不是盯着版本字符串，而是确认 replace 右侧是不是个人电脑才有的绝对路径或相对目录。

本地联调改用 go.work

如果两个模块只是正在并行开发，最适合把“本地源码优先”放到开发环境的 workspace。Go 官方 workspace 教程使用 go.work 的 use 指令把多个模块加入同一个工作区；这样可以保留每个模块自己的 go.mod，也不必把临时路径写入共享模块文件。

# 在包含两个模块的本地工作目录创建 workspace。
go work init ./order ./shared

# 后续新增本地模块时，把它加入 workspace。
go work use ./tools

# 确认 workspace 中有哪些主模块。
go work edit -json

对应的 go.work 可以是下面这种简洁结构：

go 1.23

use (
	./order  // 业务服务模块。
	./shared // 正在本地联调的共享模块。
)

这里的关键是职责分离：开发机通过 go.work 看到本地模块，提交给团队和 CI 的 go.mod 仍然描述可发布的依赖。是否提交 go.work 要看仓库布局是否对所有成员一致；如果每个人的目录结构不同，就把它作为本地工作区文件管理，避免把个人路径变成团队契约。

让 CI 使用正式版本依赖

当共享模块已经有仓库和版本时，CI 应该走模块版本，而不是依赖构建机上的兄弟目录。先移除只服务本地联调的 replace，再让 require 指向一个 CI 能访问的版本。版本可以是已经发布的标签，也可以是仓库可访问的提交对应版本；具体认证方式取决于你的私有模块环境，本文不展开。

# 从主模块的 go.mod 中删除本地替换。
go mod edit -dropreplace=example.com/shared

# 选择 CI 可以获取的共享模块版本。
go get example.com/shared@v0.4.0

# 让依赖声明回到当前源码实际使用的集合。
go mod tidy

官方文档特别强调，单独的 replace 不会把模块加入依赖图，通常仍然需要一个对应的 require。因此不要只删除 replace 就结束迁移：如果没有可获取的版本，CI 仍会因为缺少模块来源而失败。迁移后的提交至少应同时包含一致的 go.mod 与 go.sum 变化。

在 CI 中显式关闭隐藏的 workspace

即使仓库没有提交 go.work，构建机的上级目录也可能存在一个 workspace 文件。为了让 CI 模拟干净的单模块构建，可以在流水线命令前显式设置 GOWORK=off。这样做不是为了替代依赖管理，而是为了尽早发现“只在某个开发环境成立”的隐式来源。

# 强制 CI 按当前模块的 go.mod 工作，不读取上级目录的 go.work。
GOWORK=off go test ./...

# 构建也使用同一条单模块边界。
GOWORK=off go build ./...

如果这两条命令在 CI 中暴露出缺失模块，优先修复 go.mod 的依赖声明，而不是把构建机目录改成刚好能通过。反过来，如果项目确实是一个需要多模块一起构建的单仓库，就把 go.work 和模块目录作为明确的 CI 输入，并在流水线中固定检出布局；不要让它依赖某台机器的父目录状态。

三种方案怎么选

我的取舍通常是：开发阶段用 go.work，合并到主分支前切回正式模块版本，CI 再用 GOWORK=off 运行一次模块边界检查。只有当多个模块本来就属于同一个可控仓库，并且检出布局是明确契约时，才考虑把固定相对路径纳入 CI。

相关问题

只在本机临时加 replace，为什么仍可能影响 CI？

只要修改后的 go.mod 被提交，CI 就会读到这条替换。未提交的修改不会进入 CI，但它也不会进入团队复现路径，容易让本地与提交状态继续分叉。

go.work 能替代 go.mod 吗？

不能。go.work 描述本地或多模块工作区，模块自身的依赖声明仍在 go.mod 中。发布模块或让独立 CI 构建时，不能把 workspace 当成可下载的依赖版本。

删除 replace 后为什么还要检查 go.sum？

删除替换会改变模块图的来源，正式版本可能带来新的校验和或间接依赖。用目标版本重新整理后，应把与这次迁移对应的 go.mod、go.sum 变化一起提交。

这次问题给我的经验是：replace 很适合把本地开发速度拉起来，却不适合默默承担 CI 的依赖发布职责。把本地源码优先放进 go.work，把 CI 依赖落到可访问版本，再用 GOWORK=off 暴露隐藏状态，通常就能让“我这里能编译”的问题变成一条清楚的迁移路径。