Go doc pkg@version 为什么找不到本地 replace 模块

go doc pkg@version 查的是指定模块版本里的包文档，不是“把当前目录的本地替换目录直接挂到命令行”。所以 go.mod 里虽然有 replace，只要没有匹配的 require、左侧版本不一致，或者实际使用了另一份模块文件，仍然会出现找不到包的提示。

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

我排查这类问题时，先把“查询指定版本”和“使用当前工程依赖图”拆开，再看替换是否真正参与解析。下面只围绕模块路径、版本和本地 replace 展开。

先分清 pkg@version 到底在查什么

@version 是模块版本查询的一部分。它表达“到某个模块版本中寻找包或符号”，并不等于“使用我当前工作区旁边那份源码”。而本地 replace 是主模块对依赖内容来源的改写，作用前提是那个模块已经进入依赖图。

最容易忽略的是，replace 单独出现不会把模块加入构建列表。一个可解释的最小关系应该同时有 require 和 replace：

// 文件：app/go.mod；require 先把目标模块放进主模块依赖图。
module example.com/demo/app

go 1.23

require example.com/demo/widget v0.0.0

// 相对路径指向本地模块根目录，而不是任意源码子目录。
replace example.com/demo/widget v0.0.0 => ../widget

../widget 目录还必须有自己的 go.mod，且其中的 module 路径要与被替换的模块身份一致。只写一个同名的 widget.go，不能代替模块根目录。

为什么 replace 看起来没有生效

我遇到过的“找不到本地模块”通常落在四个位置。第一，只有 replace 没有对应 require；第二，左侧写了 v0.0.0，但最终选中的却是另一个版本；第三，命令读取的不是预期主模块；第四，go.work 的规则覆盖了单个 go.mod 的判断。

有版本限定的替换只匹配那个版本；省略左侧版本才表示匹配该模块的所有版本。排查时不要先删版本限定，而是先确认模块图中实际选中了什么。下面的命令是读者可在自己的工程中使用的检查示例：

# 先确认当前命令实际选中的主模块与工作区文件。
go env GOMOD GOWORK GOFLAGS

# 查看构建列表中的模块信息，JSON 字段可用于定位 Replace 与 Dir。
go list -m -json example.com/demo/widget

# 关闭工作区只用于做单模块对照，不会修改项目配置。
GOWORK=off go list -m -json example.com/demo/widget

如果返回信息显示替换目标目录，说明规则参与了解析；如果错误是目标目录没有 go.mod，那是输入布局问题，不是 go doc 把 replace 忽略了。反过来，如果根本没有预期的 Replace 信息，就继续核对 GOMOD、GOWORK、GOFLAGS 和左侧版本。

当前工程、指定版本和本地路径不是同一个目标

这三个命令的目标不同：

如果你的目的只是看本地改动后的 API，我更倾向于从主模块根目录使用包路径，例如 go doc ./widget 或项目内的完整包路径；如果目的是比较某个发布版本，就使用 pkg@version，不要期待本地替换改变一个脱离当前工程的版本查询。

同仓多模块还要考虑 go.work。它可以声明工作区模块并提供替换规则，工作区级配置可能覆盖模块文件中的同类规则：

// 文件：go.work；use 让多个本地模块进入同一工作区。
go 1.23

use (
    ./app
    ./widget
)

// 工作区替换影响工作区内的模块解析；发布契约仍需单独检查。
replace example.com/demo/widget => ./widget

按一个稳定顺序处理报错

完整工作流可以压缩成四个检查点。先确认当前目录与 GOMOD，避免命令落在另一个主模块；再确认目标模块的 require 和实际选中版本；然后查看 Replace 是否指向一个含 go.mod 的本地模块根；最后才决定用指定版本查询，还是用本地包路径查询。

如果 CI 失败而本机成功，还要把同级目录和 go.work 一起当成构建输入。replace => ../widget 不会替 CI 检出目录，也不会由 go mod tidy 创建源码。若本地模块依赖其他模块，继续出现网络下载也不一定代表目标替换失败，可能只是传递依赖仍需解析。

我最后会用一句话判断修复是否到位：当前主模块是否明确 require 了目标，实际选中的版本是否命中 replace，替换目录是否带着正确的 go.mod，而查询命令是否和目标一致。四项都对上后，再处理 vendor、缓存或版本升级，定位会稳定得多。

相关问题

只写 replace 不写 require 可以吗？

不行。replace 不会凭空把模块加入依赖图，需要存在对应的 require，或者由依赖关系把它带入当前模块图。

把 pkg@version 改成绝对路径能解决吗？

不能把两种目标混为一谈。绝对路径只是路径写法；想查看本地源码，应使用当前模块可识别的本地包路径，并先确认主模块文件。

为什么关闭 GOWORK 后结果变了？

因为工作区可能加入了其他模块或覆盖了替换规则。关闭它适合做单模块对照，但最终要按项目实际构建命令确认工作区是否属于正式输入。