Go replace 指向本地路径为何在 CI 失效

Go 项目在本机能构建，到了 CI 却提示找不到 replace 的本地目录，通常不是 Go 忽略了替换规则，而是流水线拿到的源码树和开发机不同。本地路径按主模块 go.mod 所在位置解释；如果它指向仓库外的兄弟目录，CI 没有 checkout 那个目录，替换自然无法成立。

排障时先记住三个事实：替代目录必须包含 go.mod；本地路径替换不能写替代版本号；replace 只在主模块的 go.mod 中生效，而且还需要一个对应的 require。下面只讨论本地路径与 CI 构建输入，不把路径问题归因于网络代理。

• 开发机成功：本地目录存在，工作目录和文件布局满足相对路径。
• CI 失败：checkout 不完整、工作目录不同、目录未提交，或替代模块缺少 go.mod。
• 修复目标：让 CI 明确拿到替代模块，或者把替代关系改成可获取的远程版本。

先看本地路径到底相对于哪里

下面的结构假设两个模块都在同一个仓库内。replace 的 ./libs/payment 是相对于主模块 go.mod 的路径，不是相对于 CI 脚本文件，也不是相对于某个开发者在终端里执行命令时的目录。

repo/
  service/
    go.mod
  libs/
    payment/
      go.mod
      payment.go

// service/go.mod：相对路径从这个文件所在目录解释
replace example.com/payment => ../libs/payment

如果 CI 只 checkout 了 service/，或者把仓库内容复制到另一个布局，../libs/payment 就不再指向替代模块。开发机上可用的绝对路径更不适合写进提交的 go.mod：它把个人目录结构带进了构建输入，也无法在干净 runner 上复现。

替代目录必须像一个完整模块

本地路径不是随便指向一组 Go 文件。Go 官方模块规则要求本地替代目录包含 go.mod；如果替代模块有 module 声明，它应与左侧被替换的模块路径相匹配。常见错误是只提交了 payment.go，却漏掉了 libs/payment/go.mod，或者把 module 写成了不一致的路径。

module service.example/internal/service

go 1.23

require example.com/payment v0.0.0-replace

// 本地替换只写路径，不在右侧追加版本号。
replace example.com/payment v0.0.0-replace => ../libs/payment

module example.com/payment

go 1.23

// 替代模块可以有自己的依赖，CI 也必须把这个文件提交并带入构建上下文。

这里的伪版本只用于让 require 选中一个被替换的模块；它不是要从网络下载的发布版本。单独写 replace example.com/payment => ../libs/payment，但主模块没有 require 这个路径时，替换不会主动把模块加入模块图。

为什么本机成功而 CI 仍然失败

可以把差异分成四类。第一类是输入缺失：CI 使用浅 checkout、稀疏 checkout 或只上传子目录。第二类是路径基准不同：构建命令进入了另一个主模块，实际生效的不是你修改的那份 go.mod。第三类是模块文件不完整：替代目录没有 go.mod，或 module 路径不一致。第四类是作用域误判：依赖模块中的 replace 不会替调用方的主模块全局生效。

CI 里可以先运行下面这组不泄露代码和凭据的定位命令。它们只打印当前目录、模块文件路径和模块关系；不要把包含令牌的环境变量整体输出。

steps:
  - name: 定位 Go 模块输入
    run: |
      # 只打印路径和模块元数据，不输出环境变量中的凭据。
      pwd
      find .. -name go.mod -print
      go env GOMOD GOPATH GOPROXY
      go list -m -json all
      test -f ../libs/payment/go.mod
      grep '^module ' ../libs/payment/go.mod

如果 go env GOMOD 指向的不是预期主模块，先修正 CI 的 working-directory。如果 find 找不到替代模块，修复 checkout 范围；如果文件存在但 go list -m 仍失败，再检查目录名、module 声明和 require 版本是否成套。

三种修复方式怎么选

go.work 的 use 适合把多个本地模块纳入同一个工作区，但它不是自动修复缺失目录的开关。若 CI 只需要构建稳定版本，直接删除临时本地替换并使用可访问的版本，通常比把个人目录结构硬塞进流水线更容易维护。

常见问题

replace 写了为什么还要 require？

replace 负责改变已选模块的内容来源，不负责单独把模块加入模块图。主模块仍需要通过 require 选中左侧路径。

本地路径能不能写绝对路径？

语法上可以，但绝对路径通常绑定某台机器的目录布局。提交到 CI 前应优先使用仓库内稳定的相对路径，或切换到远程模块版本。

依赖模块自己的 replace 为什么没生效？

Go 的 replace 主要作用于主模块的模块图。调用方不能指望依赖模块提交的本地替换自动改变自己的构建输入，应在调用方主模块或明确的工作区中配置。

官方资料：https://go.dev/ref/mod、https://go.dev/doc/modules/gomod-ref。排查顺序可以固定为：主模块位置 → checkout 文件 → 替代模块 go.mod → require/replace 配对 → CI 作用域。