Go 1.25 go doc -http 怎么查看本地 API：文档服务启动与端口排查

本地查 Go 标准库时，来回切换终端、源码和在线文档很容易漏掉当前模块的版本。Go 1.25 给 go doc 增加了 -http 选项，可以直接启动一个文档服务，再用浏览器查看指定对象；它适合查本机工具链里的 API，不等于把文档发布到公网。

想快速查看本地 API，先运行 go doc -http net/http，再确认终端显示的监听地址；如果端口被占用，先处理监听冲突，不要把问题误判成包不存在。

go doc -http 到底解决了什么

普通的 go doc net/http 把说明打印到终端，适合查一个函数或字段；加上 -http 后，Go 工具会启动本地 HTTP 文档服务，并让浏览器呈现包、类型和方法之间的链接。文档内容来自当前 Go 安装和可解析的模块，不会自动替代 pkg.go.dev 的在线版本。

先用一个标准库包试跑：

go version
go doc -http net/http

正常时，终端会给出本地监听地址，浏览器随后打开 net/http 的文档页。这里记住两个事实：go doc 是命令入口，-http 是模式开关，net/http 是要看的对象。

为什么指定包后仍可能看不到想要的对象

go doc -http net/http 展示的是包级文档。若要查具体类型，可以把对象写得更窄，例如：

go doc net/http.Server
go doc net/http.NewServeMux

HTTP 模式和对象查询不是一回事：-http 负责启动可点击的文档服务，而 net/http.Server 或 net/http.NewServeMux 决定当前查询对象。对象名拼错时，先用不带 -http 的命令确认名称，再回到浏览器范围查阅。

端口打不开时按这条路径排查

浏览器报“无法访问”时，先看终端进程是否仍在运行，再看监听端口是否已被其他程序占用。不要连续启动多个 go doc -http，否则第二次失败只说明地址冲突，不能说明文档包有问题。

go doc -http net/http
lsof -nP -iTCP:6060 -sTCP:LISTEN

如果终端给出的地址不是 6060，以实际输出为准；示例里的端口只是用于说明排查思路。关闭占用端口的进程后重新启动一次，或直接使用第一次启动成功的地址。看到 net/http 的包概览、类型链接和方法列表，才算文档服务真的可用。

本地文档和 pkg.go.dev 怎么选

查当前机器安装的 Go 版本、标准库行为或本地模块时，本地文档更贴近实际环境；查第三方模块的发布版本、示例和版本标签时，pkg.go.dev 更方便。两者显示内容不一致时，先核对 go version 和模块版本，再判断是版本差异还是对象路径写错。

常见问题与边界

go doc -http 会把文档公开到互联网吗？

它用于本地查看。是否能被其他机器访问取决于监听地址、网络和防火墙配置，不应把它当作生产文档站点。

为什么命令能运行但浏览器没有自动打开？

自动打开浏览器不是判断成功的唯一条件。以终端给出的监听地址为准，手动粘贴到浏览器；只要包概览能显示，文档服务就已启动。

查不到方法时该先改端口吗？

不用。先用 go doc 包名.对象名 核对对象名和导出状态；端口问题只影响访问，不会改变 API 是否存在。

把这条命令留成自己的检查习惯

遇到“本地 API 和网页说明对不上”时，先记录 go version，再用 go doc -http 查看当前工具链里的包，最后用对象级命令确认类型或方法。这样能把版本差异、端口冲突和名称拼写三个问题分开，排查会快很多。