Go 1.27 go doc package@version 查询怎么使用

在升级依赖前查 API，最容易遇到的误判是：当前项目能看到的文档，不一定就是你准备采用的那个版本。Go 1.27 给 go doc 加上了 package@version 形式，可以直接查询指定模块版本的包文档，不必先改项目的 go.mod。

最小用法是 go doc example.com/pkg@v1.2.3。它适合做版本对照和升级评估；它只查看文档，不会把依赖写入当前项目。

为什么升级评审会需要这个查询

假设项目当前依赖 example.com/metrics 的旧版本，但评审准备引入 v1.2.3。直接运行 go doc example.com/metrics，结果可能受当前模块图影响；先编辑 go.mod 再查又会把“看文档”变成一次依赖变更。Go 1.27 的新形式把两个动作分开：版本写进查询，项目文件留在原处。

最小命令怎么写

先确认命令行版本，再传入完整模块路径和版本号：

# 先确认当前命令是否来自 Go 1.27 或更高版本
go version

# 查询指定模块版本的包级文档，不修改当前项目
go doc example.com/metrics@v1.2.3

这里的 example.com/metrics 只是示例模块路径，实际使用时替换成目标模块中的包路径。版本建议先用已经发布的 v1.2.3 这类明确值，便于评审记录和复现。

包级文档不够时怎样缩小范围

go doc 原有的阅读选项仍然可用。需要完整导出文档时加 -all，只看每个符号一行摘要时用 -short，查看声明和函数体时用 -src。也可以把符号作为第二个参数传入：

# 只看指定版本中的 Client 类型
go doc example.com/metrics@v1.2.3 Client

# 查看包内全部导出文档
go doc -all example.com/metrics@v1.2.3

# 阅读符号源码；输出可能包含未导出细节
go doc -src example.com/metrics@v1.2.3 Client

第二个参数适合已经知道符号名的场景。若只想浏览 API 变化，先看包级输出，再用 -short 和具体类型缩小范围，通常比一上来打印全部源码更容易比较。

失败时按四个条件排查

还有一个边界很关键：带 @version 的查询面向模块路径，不接受本地相对路径或绝对路径。要看工作区里的本地包，仍然使用不带版本的 go doc ./path/to/pkg，不要把两种语法拼在一起。

把它放进升级流程

实际评审可以固定成三步：先用 go doc old/module@旧版本 Type 保存旧 API 认识，再用同样格式查询新版本，最后对照发布说明和项目测试决定是否修改依赖。这样查看文档不会污染分支，版本号也能直接写进评审记录。需要安装、运行或更新依赖时，仍应使用对应的 go get、go install 或项目自身的依赖流程，不能把 go doc 当成变更命令。

常见问题

Go 1.26 能运行 package@version 吗？

这个语法是 Go 1.27 新增能力。旧版本不应作为该命令的运行环境，先用 go version 确认。

查询指定版本会改动 go.mod 吗？

不会。版本查询会以模块模式加载目标版本，并忽略当前目录的根模块配置；它的用途是读取文档。

为什么不能写 ./pkg@v1.2.3？

./pkg 是本地路径，@version 是模块版本查询，两者边界不同。需要查看本地代码时去掉版本后缀。

Go 1.27 的这项改动很小，却把“查哪个版本的 API”从项目依赖变更里独立出来。记住一条命令即可：go doc 模块路径@明确版本；其余选项只负责缩小阅读范围。