Go replace 指向本地目录后 CI 为什么找不到依赖

Go 项目里的 replace 指向本机绝对目录时，CI 找不到依赖通常不是 Go 把替换规则“忘了”，而是 CI 的文件系统里根本没有那条路径。解决方法是把同仓库模块改成相对路径；如果只是多模块联调，用 go.work 管理工作区；如果依赖要进入流水线，就让它来自仓库、镜像或可访问的模块版本。不要把 /Users/...、C:\... 这类个人路径提交成团队配置。

判断 replace 是否适合 CI，只看替换右侧的来源在干净检出环境中是否存在，并确认该目录自己的 go.mod 能与左侧模块路径对上。

先确认 CI 看到的到底是哪一个目录

官方模块文档把 replace 定义为“把模块源码解析到另一个版本或本地目录”。因此下面这条配置在开发机上可能正常：

module example.com/app

go 1.23

require example.com/prefs v0.0.0-replace

// 这是开发者电脑上的绝对路径，换一台机器就可能不存在。
replace example.com/prefs v0.0.0-replace => /Users/alice/dev/prefs

CI 通常从一个全新的工作目录检出主仓库。即使仓库里有 prefs 目录，Go 也不会把它自动映射到 /Users/alice/dev/prefs。先检查三件事：流水线是否检出了依赖目录、相对路径是否从主模块根目录计算、替换目录下是否有 go.mod。

同一仓库的依赖改用相对路径

如果两个模块都在同一个仓库里，可以把目录随代码提交，并让右侧路径相对于主模块的 go.mod：

module example.com/app

go 1.23

require example.com/prefs v0.0.0-replace

// prefs 与 app 同在仓库根目录下，CI 检出仓库后也能找到它。
replace example.com/prefs v0.0.0-replace => ./libs/prefs

./libs/prefs/go.mod 至少要声明可被主模块使用的模块路径：

module example.com/prefs

go 1.23

// 这里的包路径应与代码里的 import 前缀保持一致。
// package prefs ...

更稳妥的修改方式是让 Go 生成规则，而不是手改一长串字符串：

# 在主模块根目录执行，路径相对于当前 go.mod。
go mod edit -replace=example.com/prefs@v0.0.0-replace=./libs/prefs

# 让依赖图和 go.sum 按当前文件重新整理。
go mod tidy

提交前可以把这个检查放进 CI。它不需要访问个人目录，只检查仓库中真实存在的结构：

# 显示主模块和工作区文件，先排除环境变量干扰。
go env GOMOD GOWORK

# 查看 Go 最终采用的模块目录和替换信息。
go list -m -json example.com/prefs

本地联调和 CI 构建不要共用一条路径

如果两个模块不在同一仓库，开发时可以用 go.work 把它们放进同一个工作区：

# 在包含两个模块的父目录创建工作区。
go work init ./app ./prefs

# 让当前工作区纳入新的模块目录。
go work use ./tools/prefs

go.work 适合本地同时修改多个模块，但不要把个人电脑上的绝对路径写进团队通用配置。若 CI 也需要联调，应该把工作区文件提交，并保证其中的相对目录在检出后存在；若 CI 只是验证一个发布中的应用，更清楚的方案是给 example.com/prefs 打版本或放到团队可访问的仓库/模块代理，再移除本地 replace。

提交前的四项反向检查

最后不要只在开发机执行一次 go test。在干净检出目录中检查实际模块来源：

1. 执行 go env GOMOD GOWORK，确认主模块和工作区没有意外指向个人目录。
2. 执行 go list -m -json example.com/prefs，检查 Dir 或 Replace.Dir 是否落在 CI 工作区内。
3. 删除本机专属的绝对路径后运行 go mod tidy，看依赖图是否仍然完整。
4. 在最小权限、全新检出的 runner 上运行 go test ./...，把路径问题提前变成提交失败。

核心原则很简单：replace 只改变当前主模块解析依赖的来源，不会把本地目录上传给 CI，也不会自动改变依赖的 import 路径。先保证来源可见，再讨论版本和缓存。

常见问题

相对 replace 是相对于执行命令的目录吗？

不是。应按主模块的 go.mod 所在位置理解；在多模块场景还要确认当前命令选中了哪个主模块或工作区。

只写 replace 不写 require 可以吗？

通常不行。replace 只改变已有模块的来源，不会单独把模块加入依赖图；主模块仍需要对应的 require。

把本机目录复制进 CI 缓存能解决吗？

不建议。缓存应加速可重复的依赖获取，不能替代仓库、版本或模块代理；否则换 runner、清缓存或并行构建时仍会失败。