Go 多模块联调为什么仍命中缓存：用 GOWORK 与 go list 查清本地路径

如果本地模块明明改了代码，go run 或测试却仍像在使用旧版本，先不要急着改 replace。大多数问题集中在三处：命令没有发现你以为的 go.work、use 没有指向真正的模块根目录，或者当前命令被 GOWORK=off 切回了单模块模式。

最短排查路径是：先看 go env GOWORK，再看 go env GOMOD，最后用 go list -m -json 和包目录确认解析结果。下面按这个顺序定位。

先确认 Go 命令发现了哪一个工作区

在你实际执行构建或测试的目录运行：

go env GOWORK; go env GOMOD; go env GOFLAGS; go version

GOWORK 输出一个具体的 .work 文件，表示当前处于工作区模式；为空表示没有启用工作区。若环境变量显式设置为 off，则会强制使用单模块模式。GOMOD 则告诉你当前命令选择了哪个模块的 go.mod。

当 GOWORK 为空时，Go 会从当前目录向父目录搜索 go.work。因此，在 IDE、脚本和终端中切换目录后，实际命中的可能是另一个父目录工作区。需要临时指定文件时可执行：

GOWORK="$PWD/go.work" go test ./...

图1：沿着 GOWORK、当前目录和父目录搜索链确认 Go 命令实际使用的工作区。

检查 use 是否指向模块根目录

打开 go.work，重点看每个 use 路径。它必须直接指向包含 go.mod 的目录；父目录下面即使还有子模块，也不会因为写了父目录就自动全部加入。

go 1.23.0; use ( ./app ./shared )

可以用命令快速核对：

go work use -r .; go work edit -json; find . -name go.mod -print

如果 shared/go.mod 存在，却把 ./shared/pkg 写进了 use，或者把多模块仓库的父目录写进去，解析就不会按预期工作。go work use 只会为实际存在的模块目录添加指令，-r 才会递归查找。

再用 go list 证明依赖到底来自哪里

假设 app 导入了 example.com/shared/logx，不要只看 go.mod 里的版本号，直接查看模块目录：

cd app; go list -m -json example.com/shared; go list -f '{{.ImportPath}} => {{.Dir}}' example.com/shared/logx

工作区启用时，目标模块的 Dir 应该落在本地 shared 目录；如果落在 module cache，说明本地模块没有进入工作区、模块路径不一致，或当前命令根本没启用这份 go.work。官方工作区教程也用这种方式让本地模块覆盖缓存中的版本。

图2：用 go list 的模块目录结果区分本地工作区命中与模块缓存命中。

用 GOWORK=off 做一次单模块对照

在同一个模块目录分别运行：

go list -m all; GOWORK=off go list -m all; GOWORK=off go test ./...

如果第一组能看到本地模块、第二组回到缓存版本或直接无法解析，问题就在工作区边界，而不是 Go 编译器“忽略”了代码。此时优先修正 GOWORK、工作目录和 use，不要把临时联调路径写成长期 replace。

本地联调可以显式执行 GOWORK=/绝对路径/go.work go test ./...；发布和 CI 通常应测试模块脱离工作区后的真实依赖关系。Go 官方文档提醒，提交 go.work 可能让 CI 选择错误的依赖版本，除非这些模块确实只会一起开发和发布。

选择哪种修复方式

相关问题

go.work 会覆盖 go.mod 的 replace 吗？ 会。工作区中的同模块替换规则优先级更高，尤其是通配替换；因此要把它当作本地联调边界管理。

改完 shared 代码还要 go work sync 吗？ 不一定。sync 是把工作区构建列表同步回各个模块的 go.mod，不是让 Go 重新发现 use 路径的开关。

最值得保留的诊断证据是什么？ 保留执行目录、go env GOWORK、go env GOMOD 和目标包的 Dir 输出，通常足以解释“本地版本不生效”。

依据：Go Modules Reference、Getting started with multi-module workspaces。