go.mod replace 本地路径在 CI 中失效的排查方法

如果开发机上的 go test ./... 能通过，CI 却提示 replacement directory ... does not exist 或找不到替换模块，先不要急着改 Go 版本。replace 右侧写的是本地路径时，它依赖的是 CI 的实际文件系统：相对路径从主模块目录解析，目标目录还必须是一个包含 go.mod 的模块。开发机和 CI 的检出目录不一致，通常就足以让同一份 go.mod 得出不同结果。

官方文档：https://go.dev/ref/mod

排查顺序应当固定为：先确认 CI 中路径存在，再确认替换目录有 go.mod，然后确认 module、require 和 replace 的模块路径与版本确实命中，最后再判断当前 replace 是否写在主模块的 go.mod 中。

先看清本地 replace 依赖的运行条件

例如主模块目录为 service，go.mod 中写着 replace example.com/shared => ../shared。这不是“从网络下载 shared”，而是要求执行 Go 命令时，service 的上一级目录中确实存在 shared。CI 如果只检出了 service 仓库，或者把仓库放在不同的目录层级，../shared 就可能指向空位置。

本地路径替换还有两个硬条件：右侧路径必须指向模块根目录，且该目录需要有 go.mod；如果替换模块有 module 指令，它应当与左侧被替换的模块路径一致。replace 本身也不会把模块加入模块图，仍需有对应的 require。

第一步：在 CI 中确认路径到底解析到了哪里

不要只在日志里打印当前目录后凭感觉判断。让 CI 在执行构建前，直接从主模块目录输出 go env GOMOD，并检查 replace 右侧对应的目录。下面的示例假定主模块和本地模块位于同一检出根目录：

set -eu

# 进入真正包含主模块 go.mod 的目录，避免工作目录变化造成误判。
cd "$CI_PROJECT_DIR/service"

# 输出 Go 实际使用的主模块文件，确认不是在仓库根目录误执行。
go env GOMOD

# 相对路径 ../shared 必须在 CI 的文件系统中真实存在。
test -d ../shared
test -f ../shared/go.mod

# 让模块命令直接解析当前依赖图，尽早暴露路径或模块文件问题。
go list -m all >/dev/null
go test ./...

这里的重点不是增加一条“万能 CI 命令”，而是让错误发生在最接近根因的位置：如果 test -d 失败，问题在检出范围或工作目录；如果目录存在但 test -f 失败，问题在模块布局；只有两项都通过后，才值得继续看模块路径和版本。

第二步：检查替换模块自身的 go.mod

本地替换目录不是任意源码文件夹。它应该有自己的 go.mod，并且文件中的 module 路径要和主模块左侧的替换目标对应。例如：

// 这是主模块 service/go.mod 中的最小依赖关系。
module example.com/service

go 1.23

require example.com/shared v0.0.0-replace

// 相对主模块目录定位到同级的 shared 模块。
replace example.com/shared v0.0.0-replace => ../shared

// 这是 ../shared/go.mod，module 路径要与 replace 左侧对应。
module example.com/shared

go 1.23

如果 CI 检出的 shared 是旧目录、子模块没有初始化，或者构建脚本复制文件时漏掉了 go.mod，就会出现本地能用、CI 失败的差异。尤其不要只复制 shared 下的 *.go 文件来“模拟”模块；这样会丢失模块边界和依赖声明。

第三步：确认 require 真的命中了 replace

一个常见误区是只写 replace，却没有对应的 require，或者 require 的模块路径与左侧不一致。可以在 CI 中查看模块图和 JSON 信息：

set -eu

# 在主模块目录执行，避免看到另一个模块的依赖图。
cd "$CI_PROJECT_DIR/service"

# 输出模块图，确认目标模块确实参与当前构建。
go list -m all

# 查看目标模块的路径、版本和目录，便于发现替换没有命中。
go list -m -json example.com/shared

如果目标模块没有出现在模块图中，先检查导入路径是否仍然是 example.com/shared/...，以及 require 是否引用了同一个模块路径。若目标模块出现但目录不是预期的 ../shared，说明当前执行的主模块或生效的 go.mod 不是你以为的那一份。

第四步：别把依赖模块里的 replace 当成全局配置

replace 只对主模块的模块图生效。假设 service 依赖一个已经发布的 example.com/adapter，而你把本地替换写进了 adapter/go.mod，那么构建 service 时不会自动继承这条本地路径。开发机上如果恰好在 adapter 目录测试，容易误以为配置已经覆盖整个工程。

多模块仓库要明确 CI 的入口：要么在主模块 go.mod 中声明需要替换的模块，要么使用经过审查的 go.work 管理本地联调，并在 CI 中明确执行哪个工作区。不要依赖开发机的隐式环境变量或个人目录布局。

保留本地替换，还是改用可发布模块

如果这个替换模块就是同一仓库中的联调代码，可以让 CI 同时检出两个模块，并固定工作目录层级；也可以把它们放在一个仓库的明确子目录中，再用稳定的相对路径。关键是让开发机、CI 和构建脚本共享同一份目录契约。

如果替换只是临时验证某个分支或补丁，CI 更适合使用可访问的分支、提交或版本模块，而不是依赖开发者电脑上的绝对路径。发布给其他模块使用时尤其要注意：主模块中的本地 replace 不会自动传递给下游使用者，下游需要能够获取真实模块版本。

一张表记住常见现象

结论

go.mod 的本地 replace 在 CI 中失效，核心通常是“同一份配置没有同一份文件系统”。先确认主模块位置和右侧目录存在，再确认替换模块的 go.mod、module、require 与作用域，最后决定是补齐 CI 检出结构，还是让依赖回到可发布的模块来源。把这套顺序固化到 CI 日志后，类似故障就不会停留在“开发机明明能跑”的猜测上。

相关问题

• replace 的相对路径是相对仓库根目录吗？不是，它应按 Go 命令使用的主模块目录理解，实际入口应通过 go env GOMOD 确认。
• 只写 replace 不写 require 可以吗？通常不行，replace 本身不会把模块加入模块图，需要存在对应的 require。
• CI 可以直接保留开发机的绝对路径吗？不建议，绝对路径通常只在单台机器成立，应改为稳定检出布局或可获取的模块版本。