Go mod tidy 为什么会移除本地 replace 依赖

如果执行 go mod tidy 后，replace ../shared 消失，通常不是 Go“不支持本地依赖”，而是这条替换没有进入当前主模块的有效依赖图。最常见的原因是只写了 replace 没写对应的 require，或者项目代码已经没有导入该模块。先看模块关系，再改版本号，排查会快很多。

只写 replace，为什么 tidy 后会被移除

Go module 的依赖关系由模块图决定，而不是由 go.mod 里出现过哪些文字决定。replace 的职责是“如果需要模块 A，就到本地目录 B 取内容”；它本身不会产生“需要模块 A”这个关系。因此下面的写法看起来完整，实际没有把 example.com/shared 纳入主模块图：

module example.com/app

go 1.21

// 仅声明替换位置，不会单独建立依赖关系。
replace example.com/shared => ../shared

最小修复是给被替换模块一个版本占位。版本不会决定本地目录里的源码，但会让模块出现在图中：

module example.com/app

go 1.21

require example.com/shared v0.0.0-replace

// require 决定模块是否参与解析，replace 决定实际读取哪里。
replace example.com/shared v0.0.0-replace => ../shared

本地目录有 go.mod，仍然被清理怎么办

有了 require 也不代表它一定会长期保留。先确认本地模块的边界和路径：

# 在主模块目录执行，确认当前命令作用于哪个模块。
go env GOMOD

# 查看本地替换模块的声明；该文件必须存在。
sed -n '1,12p' ../shared/go.mod

# 检查模块路径是否与 replace 左侧一致。
grep '^module ' ../shared/go.mod

假设 ../shared/go.mod 写的是 module example.com/shared，那么左侧也应使用这个路径。不要把本地文件夹名当成模块路径。如果目标目录没有 go.mod，它就不是一个可直接作为 module replacement 的模块根目录。

另一个容易忽略的边界是工作目录。主模块的 go.mod 里的相对路径以该文件所在目录为基准，不以 CI 脚本当前的目录为基准。把项目复制到不同层级后，如果相对路径指向了另一个目录，错误往往表现为“依赖被移除”或“找不到包”，实际是替换目标已经变了。

用实际导入和模块图判断是不是未使用

go mod tidy 会扫描当前模块可构建的包及其依赖。若代码已经删除了对本地模块的 import，或者 import 只存在于当前构建约束不会选中的文件里，模块就可能被当作无关项清理。此时不要只盯着 replace 行，先看包路径和图：

# 列出当前模块实际能加载的包，确认 shared 的包路径是否出现。
go list ./...

# 查看主模块到 shared 的要求关系；输出为空通常说明它未进入当前图。
go mod graph | grep 'example.com/shared'

# 只预览 tidy 将要做的改动，避免排查时反复改写文件。
go mod tidy -diff

如果 go mod graph 没有相关边，而代码又确实需要这个模块，重点检查 import 路径是否以 example.com/shared 开头，以及文件是否被 //go:build 条件排除。反过来，如果模块已经没有任何有效包被引用，删除它就是 tidy 的正常结果，不应靠手工补回一条无用途的 require。

开发替换如何避免影响 CI

本地联调时可以使用 replace 指向同级目录，但这个目录不会随主模块自动进入远程仓库。更稳妥的做法是把替换写成短期开发配置，提交前用 go mod tidy -diff 检查差异，并确认 CI 能访问 require 指向的版本。

# 预览 go.mod 和 go.sum 的变化，不直接写入文件。
go mod tidy -diff

# 确认当前选择的模块版本和替换信息。
go list -m -json all

# 在没有本地替换目录的环境中，先移除开发用 replace 再构建。
go build ./...

如果团队必须在 CI 使用本地模块，应该把它作为明确的工作区布局或构建输入管理，而不是依赖开发者机器上“恰好存在”的目录。Go workspace 适合多模块联调，但它和单个模块的 replace 是两种不同的边界：前者描述工作区组合，后者描述某个主模块的依赖替换。

相关问题

replace 能不能不写 require？

可以暂时出现在文件里，但它不会单独把模块加入依赖图。只要希望主模块实际使用这个替换模块，就需要有匹配的 require，并且代码或依赖链确实用到了它。

为什么本地目录必须有 go.mod？

因为 module replacement 的右侧目录需要被识别为一个模块根目录。没有 go.mod 时，Go 无法确认它的模块路径和模块边界。

tidy -diff 和 tidy 有什么区别？

tidy -diff 只输出预计修改并在存在差异时返回非零状态，适合放进检查脚本；普通 tidy 会直接更新 go.mod 和 go.sum。