Go 1.27 go doc -ex 怎么查看可执行示例：符号查询与版本模块边界

升级到 Go 1.27 后，我在排查一个示例行为时不再先翻网页，而是直接让工具链把可执行示例源码吐出来：go doc -ex bytes.ExampleBuffer。这条命令解决的是“符号在哪、示例到底怎么写、当前工具链看的是哪个版本”三个连在一起的问题。

-ex 负责把指定示例的源码和注释列出来；package@version 负责把查询范围钉在某个模块版本。两者配合时，先确认工具链版本，再判断示例是否属于当前模块。

命令现场：先确认当前 go doc 能不能接住新参数

这次排查的触发点很简单：团队文档只写了“看 bytes.Buffer 示例”，却没有给出示例函数的完整源码。先跑版本检查，避免拿旧环境验证新行为。

go version
go doc -h

Go 1.27 的发布说明明确记录了 go doc 的两项变化：支持 package@version 语法，并增加 -ex 选项。若帮助文本里没有这个选项，优先处理 PATH 或工具链版本，而不是继续改包名。

用 -ex 把 bytes.ExampleBuffer 的源码和注释一起取出来

确认版本后，查询一个已知的标准库示例：

go doc -ex bytes.ExampleBuffer

输出重点不是函数返回值，而是示例函数本身、示例注释以及它展示的调用顺序。你会看到 bytes.Buffer 被写入内容，再读取为字符串，最后由示例输出进行校验。这个结果比只看类型文档更适合复现“示例为什么这样写”的上下文。

这张图对应的链路是 go doc 接收 -ex，再定位 bytes.ExampleBuffer，最后输出带注释的示例源码。图中只保留命令、选项和符号三个正文节点，实际语法仍以终端输出为准。

版本边界：package@version 只控制查哪一份文档

当本地模块依赖了多个版本，直接执行 go doc example.com/pkg 可能让人误以为看到的是某个特定版本。Go 1.27 支持把版本写进查询目标：

go doc example.com/pkg@v1.2.3

这里的 package@version 是查询定位信息，和当前项目的 go.mod 不是同一件事。它不会静默改写依赖，也不会把模块升级到 v1.2.3。如果目标包不在本地缓存，工具链还可能需要访问模块代理；网络问题和符号不存在要分开判断。

判断顺序可以压缩成一条线：先看 go version 是否为 Go 1.27，再看查询目标是否带 package@version，最后把结果和项目 go.mod 的依赖要求对照。不要把查询结果直接当成升级结果。

失败时的回退路径：把工具链问题和符号问题拆开

现场最容易混淆的是两种报错。第一种是旧工具链不认识 -ex；第二种是目标包能找到，但示例符号写错。处理时按下面顺序分层：

1. 先运行 go version，记录实际命中的可执行文件版本。
2. 再运行 go doc -h，确认帮助文本包含 -ex。
3. 最后用标准库的 bytes.ExampleBuffer 做基准查询，验证命令链本身。

如果第三步成功而业务包失败，问题更可能在包路径、模块下载或示例命名；如果第二步就失败，应修正工具链 PATH。不要通过修改 go.mod 来“修复”一个命令行参数缺失。

复查清单：这次查询是否真的可复现

• 命令使用的是 Go 1.27 或更新工具链。
• go doc -h 能看到 -ex。
• go doc -ex bytes.ExampleBuffer 能返回示例源码与注释。
• 带 @version 的查询只用于定位文档版本，没有被误当成依赖升级。

相关问题

旧版本 Go 能否使用 go doc -ex？

不能按 Go 1.27 的行为假设旧版本。先用 go doc -h 检查当前二进制是否提供该选项。

go doc -ex 会运行示例代码吗？

它的作用是列出可执行示例的源码和注释，不等于替你编译或运行示例。

package@version 会修改 go.mod 吗？

不会。它只限定这次文档查询的包版本，项目依赖仍由 go.mod 和其他模块命令管理。

把这组命令记成“版本先验、符号查询、结果复查”三个动作，遇到示例缺失或版本混淆时，排查会比反复刷新网页更快。