Go replace 相对路径在 CI 中为什么失效

Go 的 replace 相对路径在本机能用、到了 CI 却提示目录不存在，通常不是 Go 把路径解析到了执行命令时的当前目录，而是 CI 的主模块、检出内容或目录层级与本机不同。排查时先锁定主模块的 go.mod，再确认替换目录真的存在并且包含自己的 go.mod。

官方参考：https://go.dev/ref/mod

最常见的修复顺序是：确认构建使用的 go.mod，检查相对路径从该文件所在目录解析，确认 CI 已检出目标模块，最后再判断是否应改成可下载的模块版本。

一、先搞清 replace 相对路径从哪里算

官方模块参考把右侧以 ./ 或 ../ 开头的路径定义为本地替换模块根目录，并要求该目录包含 go.mod。例如下面的布局中，./internal/codec 是相对于主模块根目录，而不是相对于 CI 脚本所在目录。

service/
├── go.mod
├── cmd/api/main.go
└── internal/codec/
    ├── go.mod
    └── codec.go

module example.com/service

go 1.23

require example.com/codec v0.0.0

// 本地联调时把依赖模块指向仓库内的目录；右侧目录必须有 go.mod。
replace example.com/codec => ./internal/codec

因此，cd service/cmd/api 后执行命令，不会把 ./internal/codec 重新解释成 service/cmd/api/internal/codec。真正需要核对的是构建命令最终采用的主模块，以及该主模块根目录下的相对位置。

二、为什么本机成功而 CI 失败

本机通常是完整仓库，且开发者从仓库根目录操作；CI 则可能使用稀疏检出、浅克隆、子模块未初始化，或者在多模块仓库中从另一份 go.mod 启动构建。常见差异可以归纳为四类：

• 目标没被检出：构建包里只有主模块，internal/codec/go.mod 所在目录没有进入工作区。
• 仓库层级变了：CI 将项目放进额外目录，脚本复制文件时却只复制了主模块文件，替换目录相对位置被破坏。
• 主模块选错：命令从包含另一份 go.mod 的目录运行，嵌套模块中的 replace 不会自动作用到当前主模块。
• 目标不完整：目录存在，但替换目标缺少 go.mod，或者其中的 module 路径与左侧被替换的模块路径不一致。

还有一个容易被忽略的边界：replace 只作用于主模块的 go.mod，依赖模块里的 replace 会被忽略；而且单独写 replace 不会把模块加入依赖图，仍需要匹配的 require。

三、在 CI 中用三组命令定位

不要先改路径或盲目增加 ../。把下面的诊断放在构建步骤前，先记录 Go 实际使用的主模块和目标目录。

# 输出当前工具链、主模块文件和工作目录，避免把脚本目录当成路径基准。
go version
go env GOMOD
pwd

# 检查替换目标的 go.mod 是否确实被 CI 检出。
test -f internal/codec/go.mod && echo "replace target exists" || {
  echo "replace target is missing" >& exit 1
}

# 查看依赖图中的模块路径和替换关系；失败时保留原始错误。
go list -m -json example.com/codec

如果 go env GOMOD 显示的不是预期主模块，先修正构建目录或明确传入正确的模块入口。若 test 失败，问题在检出范围、子模块初始化或打包步骤，而不是 replace 语法。

四、按仓库类型修复

1. 普通单仓库

确保 CI 的 checkout 步骤包含主模块和替换目录，不要在缓存步骤只保存 go.mod 与 go.sum。如果替换模块是同一仓库目录，先确认它被提交到版本库，并让构建命令从主模块根目录或其子目录启动。

steps:
  - name: checkout source
    # 完整检出仓库，保证 replace 指向的本地模块也存在。
    uses: actions/checkout@v4
  - name: inspect module
    # 先确认主模块和本地替换目标，再进入正式构建。
    run: |
      go env GOMOD
      test -f internal/codec/go.mod
      go test ./...

2. Git 子模块承载替换目标

如果目标目录来自 Git 子模块，普通检出不一定会拉取它。应在 CI 的检出配置中显式启用子模块，或者把该模块改成独立版本依赖。不能只在本地用已经初始化的子模块来判断 CI 一定具备相同内容。

- name: checkout source and submodules
  # 子模块是 replace 目标时，必须让 CI 同步其内容。
  uses: actions/checkout@v4
  with:
    submodules: recursive

3. 多模块仓库

如果仓库同时存在根模块和子模块，明确每一条 replace 属于哪份 go.mod。从根目录构建根模块时，子模块的替换规则不会自动向上生效；需要在当前主模块中声明替换，或用 go.work 统一组织本地开发工作区。

五、什么时候不应继续使用相对路径

相对 replace 很适合联调未发布的模块，但它把“仓库目录布局”变成了构建前提。如果 CI 负责发布镜像、生成跨平台制品，或者构建环境只拿到源码子集，继续依赖本地目录往往会增加维护成本。

这时可以将替换模块发布到版本库或内部模块代理，再使用带版本的模块路径替换：

module example.com/service

go 1.23

require example.com/codec v1.4.2

// 发布构建使用可下载版本，避免依赖 CI 的本地目录布局。
replace example.com/codec => corp.example.com/codec v1.4.2

如果只是临时验证一个未发布提交，保留相对路径并补齐 CI 检出即可；如果要让任何干净环境都能复现，优先使用版本化模块。不要把绝对路径写进 go.mod，那只能在单台机器上成立。

六、一个最小判断表

结语

Go replace 相对路径失效时，核心不是调整命令执行位置，而是恢复“主模块根目录、替换模块目录、目标 go.mod”三者的对应关系。先用 go env GOMOD 和文件存在性确认事实，再根据构建用途决定保留本地替换还是切到版本化依赖。

常见问题

replace 右侧可以不写版本号吗？

右侧是 ./ 或 ../ 本地路径时不写版本号；右侧是模块路径时需要版本号。

只写 replace 为什么依赖仍然找不到？

replace 只改变已有模块的内容来源，不会单独把模块加入模块图。需要有匹配的 require。

CI 一定要从 go.mod 所在目录执行命令吗？

不一定。关键是 Go 识别到的主模块必须正确，且相对替换目标相对于该主模块的位置真实存在。