go doc pkg@version 查看指定模块 API 的检索方法

查询历史版本 API 时，先确认工具链版本：Go 1.27 开始支持 go doc package@version。使用完整包路径和固定版本即可查看该版本的文档，再用独立参数指定函数或类型。较旧工具链应在临时模块中固定依赖后查询。本文以 github.com/google/uuid 的 v1.6.0 为例，区分版本文档、项目依赖与兼容性判断。

目标和边界：查到指定版本，不改变检索对象

“这个函数在旧版本是否存在”与“项目实际使用哪个实现”是两个问题。前者适合指定版本查询；后者要结合当前模块、工作区和 replace 指令。固定版本可以避免跟随 latest 漂移，但不能单凭文档判断升级后的业务行为。

Go 1.27 发布说明明确增加了 go doc 的版本后缀支持。先执行下面两条命令，确认实际调用的 Go 工具以及本机帮助；多工具链环境应以当前命令的结果为准。官方依据：https://go.dev/doc/go1.27。

# 确认工具链与本机命令帮助
go version
go help doc

本文命令是操作示例，并未声称已在读者的网络、私有仓库或工程环境中执行。首次查询可能访问模块代理或下载源码，已有缓存也不代表任意版本均可离线获取。

全流程总览：把包路径、版本和符号分开

一次检索包含四个输入：支持该语法的工具链、目标包的完整导入路径、所属模块的版本、可选的符号名称。版本属于模块，文档对象是包；模块根路径与子包路径不一定相同。对于 v2 及以后采用路径主版本的模块，包路径也必须包含对应的 /v2 等部分。

示例选择已有 v1.6.0 文档的 uuid 包。先查看包级说明，再缩小到 NewString 函数，可避免把“包没找到”和“符号不存在”混为一谈。对应的版本文档可参考 https://pkg.go.dev/github.com/google/uuid@v1.6.0；该页面列出了 NewString，签名为 func NewString() string。

阶段拆解：先定位版本，再定位声明

# Go 1.27 及以上：查看指定版本的包
go doc github.com/google/uuid@v1.6.0

# 将符号作为第二个参数，避免路径和名称混写
go doc github.com/google/uuid@v1.6.0 NewString

# 确实需要浏览完整导出文档时再加 -all
go doc -all github.com/google/uuid@v1.6.0

参数中的 github.com/google/uuid 是包路径，v1.6.0 是模块版本，NewString 是包内符号。不要把仓库网页地址或 pkg.go.dev 页面地址直接作为包路径。对子包应使用该子包的完整导入路径，并在其后添加所属模块的版本。

包级查询失败时，先处理路径、版本是否存在、模块代理和访问权限；包级成功但符号查询失败时，再核对大小写、符号归属与该版本的声明。不要通过删去版本后缀来掩盖错误，那会把检索对象改成另一个上下文。

类型与方法也应先确认归属。可以先查询类型文档，再按本机 go doc 帮助支持的符号形式缩小范围。标准库随工具链提供，查询标准库时使用 go doc net/http.Client 这类形式，并记录 Go 版本。

推荐流程：让查询记录能够复现

建议把“工具链版本、完整包路径、固定模块版本、符号名、关键签名”记录在同一条笔记中。比较两个版本时分别执行固定版本查询，再比较声明和说明文字；不要把两个时间点的 latest 文档当作稳定对照。

如果真正要确认项目当前依赖，应回到项目目录查询模块信息，再运行不带后缀的文档命令。模块信息中的 Version、Replace 等字段有助于解释为什么项目看到的声明与发布版不同。

# 在目标项目目录中观察当前依赖上下文
go list -m -json github.com/google/uuid
go doc github.com/google/uuid NewString

旧版 Go 不支持版本后缀时，可以把查询放进独立临时目录。下面使用 POSIX shell 的子 shell 隔离工作目录，并对每个模块命令关闭工作区；go get 只修改临时模块的依赖文件。该做法仍需要网络、缓存和目标模块要求的工具链条件。

# 创建临时查询模块，不在业务项目中执行 go get
doc_work=$(mktemp -d) || exit 1
(
  cd "$doc_work" || exit 1
  GOWORK=off go mod init example.invalid/doclookup || exit 1
  GOWORK=off go get github.com/google/uuid@v1.6.0 || exit 1
  GOWORK=off go doc github.com/google/uuid NewString
)
# 查询目录保留在 doc_work 中，可按本地规则清理

此处没有运行 go mod tidy：一个没有导入目标包的临时模块若执行 tidy，目标依赖可能被移除。不要把临时查询得到的 go.mod 复制回正式工程。需要评估项目兼容性时，应在受控分支调整依赖并运行项目本来的构建、测试流程。

常见误区：文档版本与项目版本不是同一个证据

把新语法套到所有工具链。 go doc 在 Go 1.27 才加入该能力；更早版本报错不一定说明目标模块不存在。先看 go version，再选择直接查询或临时模块方案。

把查询当成依赖升级。 指定版本检索用于阅读发布版本。Go 命令源码对含版本后缀的查询采用独立的模块加载上下文；这不能替代项目依赖选择。源码依据：https://go.dev/src/cmd/go/internal/doc/doc.go。尤其存在本地 replace 时，发布版文档无法说明替换目录里的改动。

认为文档存在就一定可用。 文档能确认声明和注释，不能证明当前项目满足最低 Go 版本、构建标签、操作系统或外部依赖。调用方式、错误处理与迁移影响仍要结合项目验证。

为了下载私有包而随意关闭校验。 私有模块应沿用团队批准的 GOPRIVATE、代理和认证配置。公开文档站也不是私有源码检索入口。下载失败时查看具体错误，不要把敏感包名和凭据复制到公开查询页面。

速查表与常见问题

为什么网上命令能用，本机却报错？

首先检查 Go 版本。版本后缀是 Go 1.27 新增能力；随后再核对完整包路径、固定版本和网络权限，不能仅凭一条错误就认定 API 被删除。

查到 NewString 是否说明项目可以直接调用？

只能说明目标版本文档中存在该声明。项目可能选择其他版本或本地替换，还需要满足工具链与构建条件；应结合当前模块信息判断。

只查看文档，需要先在业务工程执行 go get 吗？

支持版本后缀的工具链可直接查询指定发布版本。旧工具链可使用临时模块方案；为了阅读文档而修改业务工程依赖，会增加不必要的变更。

模块版本与 go get 的正式规则见 https://go.dev/ref/mod#go-get。检索记录保留固定版本，项目判断保留真实依赖上下文，后续排查才有一致的依据。