Go replace 看似生效却仍下载远程模块：用 go list -m -json 查真实来源

在 Go 项目里，replace 写进了 go.mod，并不等于每条命令都会使用你以为的那份代码。最常见的误判有四种：左侧版本没有被 require 到、当前目录实际落在另一个主模块、工作区里的替换覆盖了 go.mod，以及本地替换目录的 module 路径不匹配。

排查时不要先盯着模块缓存里有没有压缩包，先让 go list -m -json 告诉你 build list 选中了谁、替换到了哪里；如果 Replace 不为空，优先看它的 Dir 和 GoMod。

一、先区分 replace 的两种写法

本地目录替换通常写成下面这样，右侧是相对主模块的路径，而且替换目录必须有 go.mod：

require example.com/payment v1.4.0

replace example.com/payment v1.4.0 => ./third_party/payment

它只替换 v1.4.0；如果左侧版本省略，则表示替换该模块路径的所有版本。另一种写法是替换到远程模块路径，这时右侧必须带版本，例如 example.com/payment v1.5.1。两种写法不要混成“改了 import 路径”：调用方的 import 仍然使用左侧模块路径。

二、确认当前命令读取哪一个主模块

在报错项目的入口目录执行下面的命令，把结果和你打开的文件对应起来：

go env GOMOD GOWORK GOFLAGS GOMODCACHE
go env -json | grep -E 'GOMOD|GOWORK|GOFLAGS'
go list -m

GOMOD 告诉你当前命令使用的主模块文件，GOWORK 若不是空值，则说明工作区可能加入了多个主模块；GOFLAGS 也值得检查，因为全局的 -mod 或其他模块相关选项会改变观察结果。不要只在编辑器里看某个子目录的 go.mod，命令所在目录和工作区边界才是实际上下文。

三、用 go list -m -json 读取真实来源

先看单个模块，再看整个 build list：

go list -m -json example.com/payment
go list -m -json all

重点字段可以这样读：Path 是被依赖的模块路径，Version 是左侧被选中的版本；Replace 非空表示发生了替换，替换对象里的 Path、Version、Dir 和 GoMod 描述了新来源；对于本地替换，Dir 应指向本地目录。Error 非空时先处理模块解析错误，不要把缓存里出现的下载记录当成替换失效。

四、修正 replace 未命中的配置

如果 Replace 为空，先检查左侧的模块路径和版本是否正好出现在当前模块图中；只写 replace 而没有对应 require，它不会自动加入依赖图。需要临时替换本地模块时，可以先补一个明确的伪版本，再使用本地目录：

go mod edit -require=example.com/payment@v0.0.0-replace
go mod edit -replace=example.com/payment@v0.0.0-replace=./third_party/payment
go mod edit -fmt
go list -m -json example.com/payment

如果 Replace 有值但 Dir 不对，检查相对路径是相对哪一个主模块；如果本地目录有 go.mod，其 module 指令应与被替换的模块路径一致。若使用 go.work，同时检查其中是否存在同模块的替换，因为工作区规则可能覆盖模块文件里的替换。最后用 go list -m -json all 再看一次，而不是仅凭“命令下载过文件”下结论。

相关问题

为什么 go list -m -json 不显示我没写进 go.mod 的模块？

go list -m 主要展示当前模块图中的模块；要看完整 build list 使用 go list -m -json all，并确认命令是在正确的主模块或工作区中执行。

replace 能不能改变下游用户的依赖来源？

不能把主模块里的 replace 当成可传递配置。它服务于当前主模块；发布一个供别人依赖的模块时，应通过正常版本、模块路径和依赖声明表达可复现关系。

把排查顺序固定为“当前主模块 → require 是否命中 → Replace/Dir/GoMod → 工作区覆盖”，就能把“仍然下载”与“实际没有采用替换”分开处理。