Go go.mod replace 在 CI 不生效的目录问题

go.mod 里的本地 replace 不会替 CI 下载另一份仓库。相对路径以声明它的 go.mod 所在目录为基准；CI 缺少同级目录、容器没有复制对应模块，都会让本地可用的配置在构建环境失败。应先确认正在使用哪份模块文件，再让替换目录在构建环境中按约定存在，而不是先清缓存或反复执行 tidy。

Go 官方地址：https://go.dev/

下面用 app 与 textkit 两个模块解释。路径、模块名和占位版本仅用于教学，不对应真实依赖发行版；文中命令供读者在自己的项目执行，不是本次实际运行日志。

replace 的相对路径到底以哪里为准

假设检出目录 workspace 内有 app 与 textkit 两个同级目录。app/go.mod 中声明本地替换，目标是 textkit 的模块根目录，而不是它里面某个包的目录。

workspace/
├── app/
│   ├── go.mod
│   └── main.go
└── textkit/
    ├── go.mod
    └── textkit.go

目录树只是静态布局，不是命令输出。app/go.mod 可以写成：

// 文件：app/go.mod；此处 go 1.22 是示例语言基线，不表示最新版。
module example.com/demo/app

go 1.22

// 本地替换演示用占位版本；正式发布应改为真实可获取版本。
require example.com/demo/textkit v0.0.0

replace example.com/demo/textkit => ../textkit

textkit/go.mod 的最小内容如下。它是独立模块，必须随源码一起交给 CI，不能只复制一个 textkit.go 文件来代替模块根。

// 文件：textkit/go.mod；与 app 依赖的模块身份保持一致。
module example.com/demo/textkit

go 1.22

在这个例子里，../textkit 对应 workspace/textkit。只要读取的仍是同一份 app/go.mod，从 app 的子包目录执行 Go 命令，并不会把这个相对路径改成以子包为起点。改变工作目录可能改变选中的主模块，却不是重解释同一份 replace 路径的开关。

CI 到底读了哪份 go.mod

“replace 没生效”至少有两种含义：一是规则没有参与本次模块解析，二是规则已经被选中，但目标位置不存在。两者的处理方向相反。进入预期 app 目录后，先观察环境：

# 在检出后的 app 目录执行，观察模块和工作区选择。
pwd
go env GOMOD GOWORK GOFLAGS
# 显式关闭工作区，单独观察 app 的模块配置；不持久修改环境。
GOWORK=off go list -m -json example.com/demo/textkit

对这个示例，GOMOD 应指向预期 app/go.mod。若有 go.work 或 GOFLAGS 中的 -modfile、-mod=vendor 等设置，应连同流水线命令一起看，不能只看仓库里的默认文件。在工作区中还要考虑 go.work 的替换规则；关闭工作区的命令是用于对比单模块行为，不代表所有项目都应该禁用工作区。

go list -m -json 在可正常解析时提供 Replace 与 Dir 等字段。看到 Replace 指向本地目录，说明替换关系存在；如果工具先报告无法读取目标 go.mod，则应检查那个目录的实际来源，不要把失败误判成“规则完全没有被读取”。命令也可能因为其他依赖问题提前失败，应按真实错误区分。

把被替换模块一并交给构建环境

本机往往已经有旁边的仓库，CI 默认却可能只检出 app。修复方式是显式约定布局：把 app 放在 workspace/app，把 textkit 放在 workspace/textkit，固定 textkit 的提交，然后从 app 执行构建。不同 CI 的 checkout 配置不同，但最后的相对关系应一致。

# 假设 CI 已经准备好 workspace/app 与 workspace/textkit。
cd workspace/app
# 提前报告缺失模块文件；test 命令不会创建缺失目录。
test -f go.mod
test -f ../textkit/go.mod
# 单模块模式下列出替换来源；随后执行项目自己的测试。
GOWORK=off go list -m -json example.com/demo/textkit
GOWORK=off go test ./...

这里两条文件存在判断只能确认目录输入是否具备，不能证明检出的提交就是期望提交。跨仓库联调还需要在流水线里固定并记录两个仓库的 revision，避免 app 固定而 textkit 每次追随变化的分支。

如果使用 Docker，还需要把“宿主机目录存在”和“构建阶段可见”分开。下面是构建阶段片段，接在项目已经固定 Go 工具链的 FROM 后面；从 workspace 作为构建上下文，而不是只把 app 传进去。

# 构建阶段片段：前面需要项目自己的 FROM 与固定工具链配置。
WORKDIR /src
# 两个目标目录保持同级；.dockerignore 不能排除必要源码。
COPY app/ ./app/
COPY textkit/ ./textkit/
WORKDIR /src/app
# 容器内 /src/app/../textkit 必须是真实模块目录。
RUN GOWORK=off go test ./...

Docker 的 COPY 读取构建上下文。若上下文只有 app，改写 COPY ../textkit 不是把父目录引入镜像的办法；应扩大到受控父目录，或采用已明确配置的命名上下文。例子复制完整源码是为了讲清边界，不是最优缓存层设计。只复制两份 go.mod 而不提供被替换模块源码，也不等于后续编译具备完整输入。

有 replace 为什么仍然下载依赖

replace 只改变匹配模块内容的位置，不负责凭空把一个模块加入依赖图。本文示例用 require 表达对 textkit 的依赖，用 replace 把对应内容定位到本地。只写 replace 而没有相关需求，不能据此断言该模块已进入构建。

再看左侧有没有版本限定。若写的是 replace example.com/demo/textkit v0.0.0 => ../textkit，它只匹配指定版本；最终选中的版本变了，其他版本仍按原规则解析。不写左侧版本表示替换该模块的所有版本，但应依据工程意图选择，不要把删除限定作为所有问题的通用修复。

即使 textkit 已被本地替换，其依赖的其他模块仍可能需要下载。本地替换不等于离线构建。项目如果启用了 vendor 模式，还应查看其 vendor 内容与模块元数据是否同步，避免误以为每次构建都直接读取旁边的源码；不要在尚未分清模块来源时盲目更新或删除 vendor。

发布后其他项目会继承本地替换吗

不会。在单主模块构建中，依赖模块里的 replace 不会成为消费方的替换政策。把带 ../textkit 的 app 发布出去，不会让使用者自动获得你的同级工作目录；本机联调可用和依赖可分发是两件事。

若 app 只在团队约定的多仓库流水线构建，可以保留本地目录约定，并让 CI 完整准备输入。若一个库要供别的模块正常获取，应让 require 指向真实可获取的兼容版本，避免依赖仅靠本机 replace 才存在的占位版本。消费方确实需要临时替换时，应在其自身主模块明确配置并承担维护责任。

同仓多模块可以用 go.work 支持本地联调，但发布测试仍需要确认脱离本机工作区后的模块依赖完整性。不要把工作区当成自动发布嵌套模块或替别人检出仓库的功能。

相关目录问题怎么快速判断

改成绝对路径能彻底解决吗？

绝对路径便于一次性定位，却依赖 runner 的具体布局。开发机路径不应提交为团队共享配置。优先维护相对目录契约；确需动态生成配置时，由 CI 使用明确的临时模块文件，不要修改全局 Go 环境掩盖问题。

go mod tidy 会生成被替换目录吗？

不会。它不是仓库检出工具。缺少 textkit 时，应补齐构建输入，而不是期待 tidy 创建源文件。运行 tidy 可能改动模块文件，应把依赖维护与目录故障排查分开。

为什么本地清缓存后仍正常，CI 仍失败？

本地替换直接引用磁盘目录。只要本机目录一直存在，清缓存也不能模拟 CI 缺失同级源码的情况。更有效的对照是用与 CI 相同的检出布局、工作区选择和构建上下文观察模块来源。

排查可归纳为三个问题：哪份配置生效、目标目录是否存在、这套目录关系是否属于发布契约。确认这三点后，再讨论版本选择、vendor 和网络来源，通常能避免把目录问题误修成依赖升级问题。

参考：Go Modules 的 replace 规则、go.mod 指令说明、Go 官方相对路径处理实现、Docker 构建上下文文档。