go doc package@version 怎么查看指定依赖版本的 API

升级 Go 依赖时，最容易被忽略的不是下载命令，而是“我正在看的 API 到底属于哪个版本”。本地工作区可能已经解析到较新的版本，在线文档也可能默认展示最新内容；这时直接运行 go doc 包名，很难回答旧版本是否已经提供某个类型或函数。

Go 1.27 给 go doc 增加了 package@version 查询形式，可以把文档目标固定到一个模块版本。官方资料入口：

官方地址：https://go.dev/doc/go1.27

它只负责查阅指定版本的 API，不会修改 go.mod，也不会替你完成依赖升级。本文把这条命令放进一个可复用的依赖评审流程。

go doc package@version 解决的是什么问题

关键在于把“包路径”和“版本”同时写进查询目标。假设项目依赖 example.com/telemetry，包位于模块根目录下的 trace 子目录，查询目标应当表达为模块版本与包路径的组合，而不是只写一个不带版本的短名称。

可以把这条命令理解为一张“版本化 API 目录”：package@version 指向一个确定的包，Go 工具链再从模块路径、子目录和版本信息定位对应的源码文档。它适合回答“这个版本有没有该符号”“该版本的参数和注释是什么”，不适合替代编译器验证。

先用最小命令查看包和具体符号

命令行示例可以先从模块包开始，再缩小到一个导出符号。下面的写法只展示查询意图；版本号应替换成项目需要核对的实际版本。

# 查看指定模块版本中某个包的文档
go doc example.com/telemetry/trace@v1.8.2

# 继续查看该版本包里的具体类型或函数
go doc example.com/telemetry/trace@v1.8.2.Tracer

# 需要源码上下文时，显式要求 go doc 展示源码
go doc -src example.com/telemetry/trace@v1.8.2.Tracer

第一条命令用于确认包的职责和导出成员，第二条命令把阅读范围缩小到一个符号，第三条命令用于查看声明附近的源码。若目标是标准库或模块内包，仍然要以当前 Go 工具链支持的查询语法为准；外部模块的版本必须是该模块可识别的版本查询。

不要混淆模块路径、包路径和项目依赖

“模块”和“包”不是同一个地址。模块路径来自 go.mod 的 module 声明，包路径是在模块路径后面追加子目录。版本标记通常对应模块版本，而不是某个子目录单独发布的版本。

# 查看当前主模块和构建列表中的模块版本
go list -m
go list -m all

# 查看当前项目声明与实际解析的模块关系
go mod graph

# 再单独查阅一个指定版本的包文档
go doc example.com/telemetry/trace@v1.8.2

这里有三个不同问题：go.mod 说明项目声明了什么，go list -m all 说明当前构建列表解析了什么，go doc package@version 说明某个指定版本提供什么 API。它们的结果可以互相对照，但职责不能互换。

把 API 查阅放进依赖升级评审

遇到升级候选时，建议把“当前版本”和“目标版本”分开观察。先用 go list 记录项目当前实际使用的版本，再用 go doc package@version 阅读候选版本的包级说明和关键符号；最后回到代码调用点判断签名、行为和弃用信息是否影响项目。

# 记录当前项目看到的模块版本，作为评审基线
go list -m -json example.com/telemetry

# 阅读候选版本的包级 API，不改动当前 go.mod
go doc example.com/telemetry/trace@v1.8.2

# 确认项目文件中的版本声明和 Go 版本要求
go env GOMOD
go version

如果只是想知道文档差异，停在这里即可；如果要真正升级，再使用项目既定的依赖变更流程并提交 go.mod、go.sum 的变化。不要把一次文档查询误当成依赖已经升级，也不要只凭文档存在就判断调用一定能编译。

遇到查不到时先检查这四个边界

1. 包路径是否完整：模块根路径和子包路径少一段，工具可能无法定位目标包。
2. 版本是否属于该模块：主版本后缀、标签格式和模块实际发布版本要匹配。
3. 符号是否导出：小写标识符属于包内部实现，不能按公共 API 的方式查阅。
4. 查询与构建是否分开：文档查询成功不等于当前项目能编译，最终仍需让项目自己的构建和测试验证。

此外，模块下载和缓存由 Go 工具链管理。网络、代理或缓存问题会影响命令是否能取得指定版本，但这与“该版本是否存在某个 API”是两个不同层次的问题，排查时不要混在一起。

一张表记住三个命令的分工

最短结论是：想看当前项目用的版本，用 go list；想看某个候选版本的 API，用 go doc package@version；想改变项目依赖，才进入 go get 或团队约定的升级流程。

常见问题

go doc package@version 会自动修改 go.mod 吗？

不会。它用于查阅指定版本的包文档，依赖变更仍由明确的模块操作完成。

为什么 go doc 查到的 API 仍然不能编译？

因为文档目标和当前项目构建目标可能不同。项目的 Go 版本、构建标签、依赖替换和实际导入路径都可能影响编译结果。

只写模块路径能不能代替完整包路径？

只有目标确实位于模块根包时才适合这样做；子包应写完整包路径，避免把模块地址误当成包地址。