replace本地模块后测试仍引用旧版本怎么办

replace 本地模块后测试仍像是在使用旧版本，通常不是 Go 忽略了替换，而是测试命令读取了另一份 go.mod、被 go.work 覆盖，或替换左侧模块根本没有进入当前模块图。先用 go env GOMOD GOWORK 找到生效入口，再用 go list -m -json 看最终的 Replace 和 Dir，比盯着测试输出更可靠。

官方地址：https://go.dev/ref/mod

先确认 go test 读取哪一份模块配置

很多项目目录里同时有根模块、子模块和 go.work。你在子目录执行测试时，Go 会根据当前目录寻找主模块；如果当前目录落在另一份 go.mod 下，根目录的 replace 自然不会参与解析。

# 在准备执行 go test 的同一个目录运行，确认真正生效的配置入口。
go env GOMOD GOWORK

# 列出主模块与所有模块，先看目标模块是否出现在当前模块图中。
go list -m all

GOMOD 应该指向你修改过的主模块文件；如果 GOWORK 不是空值，还要打开对应的 go.work，检查它的 use 和 replace。不要只在编辑器里改根目录的 go.mod，却从子模块或工作区入口运行测试。

检查 replace 是否和 require 配成一对

下面这种写法把模块路径 example.com/greeter 替换为上一级目录的本地模块：

module example.com/app

go 1.23

require example.com/greeter v0.0.0

// 仅替换当前主模块依赖图中的 greeter，右侧必须是另一个模块根目录。
replace example.com/greeter => ../greeter

本地替换右侧使用 ./ 或 ../ 时，目录中必须有 go.mod；该文件里的 module 行也应写成 example.com/greeter。如果只有 replace 而没有对应的 require 或传递依赖，替换没有可作用的模块版本，看起来就像没有生效。

还要留意版本范围：replace example.com/greeter v1.2.0 => ../greeter 只替换左侧的 v1.2.0；不写左侧版本才表示匹配该模块的所有版本。为了避免手工改错，可以用命令让 Go 编辑文件：

# 以主模块为基准写入本地替换，版本省略表示匹配所有版本。
go mod edit -replace=example.com/greeter=../greeter

# 重新整理依赖文件，避免 require 与 replace 的状态脱节。
go mod tidy

用 go list 直接确认源码目录

模块是否真的被替换，关键看模块详情里的 Replace 和 Dir，不要只看测试日志中打印出的业务版本字符串：

# 把模块路径换成项目实际导入的路径；输出中的 Dir 应指向本地目录。
go list -m -json example.com/greeter

# 需要时同时查看当前构建列表中该模块的版本关系。
go list -m -f '{{.Path}} {{.Version}} => {{with .Replace}}{{.Path}} {{.Version}}{{end}}' all

如果 Replace 非空且 Dir 位于预期的本地目录，模块解析已经切换成功。若查不到模块，先检查导入路径是否确实是该模块的路径；若 Dir 仍在模块缓存目录，优先回到前两步检查 GOMOD、GOWORK、require 与版本限定。

排除 go.work 和测试缓存造成的错觉

Go workspace 可以把多个模块放到同一个工作区里，并且 go.work 中的替换会覆盖工作区模块中同模块或同版本的替换。临时判断时可以显式关闭工作区：

# 只在确认项目不依赖工作区时使用，强制回到当前主模块的 go.mod。
GOWORK=off go list -m -json example.com/greeter
GOWORK=off go test -count=1 ./...

如果关闭工作区后结果才符合预期，修正的是 go.work 的 use 或 replace，不要把临时的环境变量写进项目脚本。若模块解析已经显示本地 Dir，但测试输出仍是上一次结果，再用 -count=1 禁用测试缓存；必要时执行 go clean -testcache。这一步只处理结果缓存，不会改变模块图。

按证据快速定位问题

最短的排查顺序是：go env GOMOD GOWORK → go list -m all → go list -m -json 模块路径 → 必要时 GOWORK=off go test -count=1 ./...。先定位模块解析证据，再决定是否需要清理缓存，通常不需要反复删除整个模块缓存。

相关问题

为什么只写 replace 不会生效？

因为 replace 不会单独把模块加入模块图，左侧模块还必须由主模块或传递依赖 require。先用 go list -m all 确认它确实在当前构建列表中。

本地模块的 module 名称必须一样吗？

需要一样。使用本地路径替换时，右侧模块的 go.mod 应声明被替换的模块路径，否则导入路径和模块身份对不上。

go.work 和 go.mod 同时有 replace 怎么选？

在工作区中，go.work 可以覆盖工作区模块里的同模块替换。用 go env GOWORK 找到它，再结合 go list -m -json 查看最终结果。