Go go.mod replace 使用本地路径时为什么 CI 找不到模块

本地开发能编译、CI 却提示 replacement directory ... does not exist，通常不是 Go 在 CI 中“忽略了 replace”，而是两台机器看到的文件树不同。replace ./libs/payments 里的相对路径，是相对于主模块 go.mod 所在目录解析的；CI checkout 没有这个目录、路径层级不同，或者替换目录缺少自己的 go.mod，都会让本地配置失效。

先检查 CI 工作目录和替换目录是否同时存在，再检查替换模块的 module path 与主模块的 require。开发联调可以使用本地 replace，但持续集成必须让该目录随仓库进入 checkout，或改为 CI 能下载的模块版本。

先确认 replace 到底指向了哪棵目录

假设仓库结构如下，主模块在 app/go.mod，共享模块在 libs/payments/go.mod：

app/
  go.mod
  cmd/server/main.go
libs/
  payments/
    go.mod
    charge.go

那么 app/go.mod 中应写成：

module example.com/shop/app

go 1.23

require example.com/shop/payments v0.0.0

// 本地联调：路径相对 app/go.mod，指向仓库内的共享模块。
replace example.com/shop/payments => ../libs/payments

官方规则要求本地替换右侧使用 ./ 或 ../ 开头的路径，目标目录必须包含 go.mod。如果目标模块写的是 module example.com/shop/payments，它就能作为左侧模块的本地内容使用；单独写 replace 不会自动增加 require。

在 CI 中用三组命令定位缺失的是路径还是模块

不要先把路径改成绝对路径。先在 CI job 中打印主模块位置和仓库文件：

# 确认命令从哪个主模块目录执行。
pwd
go env GOMOD

# 确认替换目录是否随 checkout 到达预期位置。
test -f ../libs/payments/go.mod && echo "replacement go.mod exists"
git ls-files ../libs/payments/go.mod

# 展开模块图，重点看 Replace、Dir 和 GoMod 字段。
go list -m -json all

go env GOMOD 如果不是预期的 app/go.mod，说明 job 的 working-directory 或命令入口不对。文件检查失败时，应回到 checkout 配置：模块可能在单独仓库、子模块没有初始化、稀疏检出排除了 libs/payments，也可能是 CI 只复制了 app 子目录。

如果目录存在但模块图仍不对，再看 go list -m -json example.com/shop/payments 的 Path、Dir 和 GoMod。Dir 应落在预期的 libs/payments，GoMod 应指向该目录下的 go.mod。注意：go list -m 的模块选择结果只说明当前主模块的配置，不代表另一个子模块也会继承这条 replace。

按仓库形态选择修复方式

如果应用和共享模块属于同一个 monorepo，最直接的修复是把两者一起 checkout，并让 CI 从包含主模块的目录执行。若仓库使用 Go workspace，也可以在仓库根目录维护 go.work：

go 1.23

use (
    ./app
    ./libs/payments
)

// 仅用于开发或同仓库 CI 的临时替换，覆盖相同模块的 go.mod replace。
replace example.com/shop/payments => ./libs/payments

go.work 适合多个主模块一起开发，但它也必须被 CI checkout，并且执行命令时要让 Go 找到它；可以在 job 中显式设置 GOWORK 或从 workspace 根目录执行。不要把个人电脑的绝对路径写进提交文件，因为它既不能在其他 runner 上复用，也会掩盖仓库没有完整 checkout 的问题。

如果共享模块实际在另一个仓库，长期方案通常是给它打版本并使用模块路径替换，或直接依赖已发布版本：

require example.com/shop/payments v1.4.0

// CI 可通过 GOPROXY 或私有代理获取固定版本。
replace example.com/shop/payments v1.4.0 => example.com/company/payments v1.4.1

这种写法不再依赖 runner 的文件布局，但右侧模块路径需要版本，且相同版本不能同时以另一来源出现在构建图中。选哪种方式，取决于共享模块是否必须和应用同提交联调。

用干净环境完成最后一轮验证

路径修好后，验证重点不是在开发机再次运行一次，而是让 CI 在干净 checkout 中执行同样的命令：

# 在主模块目录执行，检查依赖图并发现缺失的 require。
go mod tidy

# 先确认模块图，再编译测试。
go list -m all
go test ./...

如果 go mod tidy 修改了 go.mod 或 go.sum，说明提交内容与构建所需依赖并不一致；应审阅变更后提交，而不是在 CI 中静默生成。若只在某个 job 失败，比较该 job 的 checkout 深度、子模块开关、工作目录和 GOWORK，通常比继续调整 replace 文本更快。

相关问题

replace 的相对路径是相对当前 shell 目录吗？

不是。它相对于主模块的 go.mod 所在目录解析，所以应先确认 go env GOMOD，再计算 ./ 或 ../ 的层级。

只有 replace 没有 require，为什么模块仍然被下载？

replace 只描述替换规则，不会单独把模块放进模块图。主模块或依赖的 go.mod 仍需对左侧模块存在 require。

CI 可以提交 go.work 吗？

同一仓库的多模块联调可以提交，但要让 CI checkout workspace 文件及其引用的所有模块；如果只是个人临时联调，避免把本机绝对路径写进共享配置。

小结：Go CI 找不到本地 replace 模块时，按“主模块位置 → 替换目录 → 替换模块 go.mod → require 与生效范围 → 干净构建”顺序排查。只要 CI 看到的文件树和本地一致，路径替换就能稳定工作；跨仓库依赖则应尽早切换为可获取的模块版本。