Go module replace 在 CI 中为什么不生效

本机调试时，go.mod 里的 replace 明明把依赖指向了本地目录，到了 CI 却仍然下载远程版本，甚至直接报找不到替换目录。这个现象通常不是 Go 忽略了 replace，而是构建输入已经变了：CI 可能没有进入预期的主模块、没有把替换目录检出，或者替换规则根本没有命中模块图。

先在 CI 中打印 go env GOMOD GOWORK 和 go list -m -json all，确认实际主模块、工作区与 Replace 字段；再检查 require、版本和相对路径。不要只看仓库里的 go.mod 文件就下结论。

先确认 CI 保护的是哪一份模块配置

replace 只对主模块的 go.mod，或当前启用工作区的 go.work 生效。一个被其他模块依赖的库，如果把 replace 写在自己的 go.mod 里，消费者构建时不会继承这条规则。CI 还可能从仓库子目录执行命令，实际进入了另一个主模块。

# 打印 CI 当前选择的模块配置，不输出令牌或完整环境变量
go env GOMOD GOWORK

# 查看当前模块图；重点关注 Replace、Dir 和版本
go list -m -json all

# 显示命令解析到的主模块文件，便于发现工作目录错误
go env -json GOMOD GOWORK GOFLAGS

如果 GOMOD 不是预期路径，先修正 CI 的 working-directory 或构建命令。若 GOWORK 显示为 off，而替换规则只写在 go.work 中，那么 CI 不会使用这条工作区替换；可以把规则放回主模块的 go.mod，或者明确在流水线中启用并提交的 go.work。

replace 单独写着，为什么还是没有效果

最容易漏掉的是 require。replace 只改变已经进入模块图的模块内容，不会单独把一个模块加入模块图。下面这种写法看似指定了本地目录，但如果没有任何 require 指向 example.com/shared，它可能不会影响当前构建：

module example.com/app

go 1.23

require example.com/shared v0.0.0-replace

// 让本地替换目录参与当前主模块的依赖解析。
replace example.com/shared v0.0.0-replace => ./shared

本地替换时，右侧目录必须是模块根目录，并且里面有自己的 go.mod。左侧版本如果写成 v1.2.3，只会替换这个精确版本；而实际模块图里可能是另一个版本。为了覆盖该模块的所有版本，可以省略左侧版本，但要确认这不会把不应替换的版本一起接管。

# 只打印目标模块，确认最终版本和 Replace 字段
go list -m -json example.com/shared

# 查看模块图中的最终选择，避免只凭 go.mod 猜测
go list -m all

# 用 Go 工具添加精确替换，减少手写格式错误
go mod edit -replace=example.com/shared@v1.2.3=./shared

如果输出里没有 Replace，按顺序回看三件事：目标模块是否在 require 中；左侧版本是否命中实际版本；执行命令是否仍在主模块上下文中。只有这三项都成立，替换结果才有机会出现在模块图里。

本机有目录，CI 为什么找不到它

相对替换路径是相对 go.mod 或 go.work 所在位置解析的，不是相对开发者当前打开的终端目录。比如主模块位于 repo/app/go.mod，replace example.com/shared => ../shared 指向的是 repo/shared。如果 CI 只 checkout 了 repo/app，或者 Docker 构建阶段只复制了 go.mod 和 go.sum，这个目录就不存在。

# 在 CI 日志中只输出路径是否存在，避免泄露仓库外的敏感内容
test -f go.mod && echo "main go.mod: present"
test -d ./shared && echo "replacement dir: present"
test -f ./shared/go.mod && echo "replacement go.mod: present"

# 打印替换模块的声明，确认 module 路径和规则一致
sed -n '1,8p' ./shared/go.mod

修复方式是让替换模块成为仓库中稳定的目录，或者在 CI 中显式 checkout 同一仓库的完整路径；Docker 则要在运行 Go 命令前把替换目录和它的 go.mod 一起复制进去。不要把开发机的绝对路径写入提交文件，也不要为了“让 CI 通过”关闭模块校验或改用不可追溯的临时目录。

把诊断变成可审计的 CI 检查

依赖替换本质上是在控制构建输入。CI 中可以保留少量不含凭据的诊断输出，让失败时能判断是配置、目录还是版本问题；正式构建仍应使用仓库提交的配置，避免把本地开发便利带进发布流水线。

# 只记录模块解析结果，避免把完整环境变量写入日志
- name: Inspect Go module resolution
  shell: bash
  run: |
    set -euo pipefail
    echo "GOMOD=$(go env GOMOD)"
    echo "GOWORK=$(go env GOWORK)"
    # 只筛选目标模块的关键字段，便于审计替换是否命中
    go list -m -json example.com/shared | sed -n '1,24p'
    # 构建前确认本地替换模块仍然带有自己的 go.mod
    test -f shared/go.mod

如果项目只是临时联调，可以保留本地 replace，但要在团队约定中说明它只作用于当前主模块。若 CI 和生产构建需要稳定复现，更适合把修复发布成可获取的模块版本，或使用提交到仓库且目录完整的多模块布局。这样依赖来源、版本和回滚路径都更清楚。

常见误区与快速判断

• 只写 replace 不写 require：先用 go list -m all 确认模块是否进入模块图。
• 把相对路径当成工作目录相对路径：以 go.mod 或 go.work 的位置重新计算。
• 精确版本写错：让 go list -m -json 告诉你最终选择的版本，再决定是否保留左侧版本。
• 把下游库的 replace 当成传递配置：消费者只使用自己的主模块规则，不能依赖库里的 replace。

排查顺序可以压缩成一句话：先看 GOMOD/GOWORK，再看模块图的 Replace，最后看替换目录和 CI checkout。三层都能对上时，replace 在 CI 中通常就会与本机表现一致。

相关问题

为什么 go mod tidy 后 replace 还在，但构建没有变化？
先确认被替换模块仍被当前主模块使用，并检查 go list -m -json 的 Replace 字段；规则存在不等于它命中了实际模块版本。

go.work 和 go.mod 应该选哪个？
多模块本地开发可以用提交到仓库的 go.work 统一组织；单个模块的 CI 或发布构建更容易用主模块 go.mod 表达清楚。关键是让 CI 明确启用哪一个，并在日志中留下 GOWORK。

CI 中可以用绝对路径 replace 吗？
不建议。绝对路径绑定某台机器的目录布局，无法复现；应改成仓库内的相对路径、可获取的模块版本或已发布的 fork 版本。