pkg.go.dev 开放查询 API：GET-only、/v1beta，包路径有歧义时必须显式指定 module

pkg.go.dev 一直是 Go 社区查包文档和发现包的主要入口。过去它只有网页界面，工具、IDE 集成和自动化流程要拿这些数据，只能靠抓 HTML 这类容易失效的做法。现在官方提供了直接的程序化访问接口：用于查询已发布 Go 模块元数据的 pkg.go.dev API。随着 AI 辅助编码普及，工具需要高保真的上下文来推理整个 Go 生态，正式接口的必要性也更明显。

服务接口

API 采用无状态、仅 GET 的架构，便于稳定性和缓存。主要端点在 /v1beta 路径下，经过一段时间的社区反馈并确认稳定后，计划过渡到正式的 v1。

完整的端点交互参考、查询参数和响应结构见 pkg.go.dev/api 规范；机器可读的 API 契约同时以 OpenAPI 规范发布：。

核心端点

这套 API 的一条设计原则是「精度优先于便利」。作为对照：go mod tidy 遇到某个导入没有被主模块现有依赖提供时，会用「最长模块路径」规则判断需要哪个模块（正因为一个包可能由两个及以上模块提供，后续才能在不破坏现有程序的前提下切出子模块）。pkg.go.dev 网页界面在为某个包路径选择展示哪个包时，也遵循类似约定。而 API 要求模块必须被无歧义地指定：如果一个包路径同时存在于多个模块中，API 会返回候选列表并报错，要求客户端给出更具体的指定。

例如，以 example.com/a/b/c 导入的包，可能由模块 example.com/a 提供，也可能由 example.com/a/b 提供。网页界面会自动按「最长模块路径」解析成 example.com/a/b；调用 API 的客户端则必须显式指定 module，否则会遇到歧义解析错误。

指定版本

对于获取包、模块或符号信息的端点，可以用可选的 version 查询参数指定版本。默认返回模块或包的最新版本。该参数支持：

• 语义版本：取某个发布 tag 的数据，例如 ?version=v1.2.3 或 ?version=v0.6.0。
• 分支名：引用默认开发分支，具体是 master 或 main，例如 ?version=master。API 会自动把分支解析成对应的伪版本。自定义或任意分支名不被支持。

省略 version 时，API 默认按该包或模块最新的打 tag 版本解析请求。

示例：直接发 API 请求

获取某个包的元数据，用 jq 格式化：

$ curl https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp | jq .
{
"modulePath": "github.com/google/go-cmp",
"version": "v0.7.0",
"isLatest": true,
"isStandardLibrary": false,
"goos": "all",
"goarch": "all",
"path": "github.com/google/go-cmp/cmp",
"name": "cmp",
"synopsis": "Package cmp determines equality of values.",
"isRedistributable": true
}

查询 master 分支版本，可以看到它被自动解析成对应的伪版本：

$ curl -s "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp?version=master" | jq '{path, version}'
{
"path": "github.com/google/go-cmp/cmp",
"version": "v0.7.1-0.20260310220054-34c9473539b8"
}

pkgsite-cli 参考实现

官方的参考客户端实现是 pkgsite-cli，可以作为自行集成的示例，演示如何直接在终端里处理这些数据。注意 API 仍在演进，这个命令的接口和行为可能变化。

安装：

$ go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest

搜索包：

$ pkgsite-cli search "uuid"
github.com/google/uuid
Module:   github.com/google/uuid@v1.6.0
Synopsis: Package uuid generates and inspects UUIDs.
... more

查看某个包：

$ pkgsite-cli package github.com/google/go-cmp/cmp
github.com/google/go-cmp/cmp
Name:      cmp
Module:    github.com/google/go-cmp
Version:   v0.7.0 (latest)
Synopsis:  Package cmp determines equality of values.

查看哪些包导入了某个包：

$ pkgsite-cli package --imported-by github.com/google/go-cmp/cmp
...
Imported by:
cloud.google.com/go/internal/testutil
cuelang.org/go/internal/cuetxtar
chainguard.dev/apko/pkg/build/types
... more

列出包声明的符号：

$ pkgsite-cli package --symbols github.com/google/go-cmp/cmp
...
Symbols:
type Indirect struct{}
type MapIndex struct{}
type Option interface{}
... more

列出模块版本：

$ pkgsite-cli module -versions github.com/google/go-cmp
github.com/google/go-cmp
Version:          v0.7.0 (latest)
Repository:       https://github.com/google/go-cmp
Has go.mod:       yes
Redistributable:  yes

Versions:
v0.7.0
v0.6.0
v0.5.9
... more

同时列出模块的版本和包：

$ pkgsite-cli module -packages -versions github.com/google/go-cmp
...
Packages:
github.com/google/go-cmp/cmp             Package cmp determines equality of values.
github.com/google/go-cmp/cmp/cmpopts     Package cmpopts provides common options for the cmp package.
... more

这个命令处理了分页和格式化，写脚本或手工排查时可以直接取需要的数据。更多用法见 pkgsite-cli 文档。

稳定性与后续

接口能力后续会扩展，同时会保持向后兼容，让已有集成继续可用；但 pkgsite-cli 参考客户端的命令行接口尚未稳定。反馈可以通过 issue tracker 提交。

落到工程上：以前靠抓 pkg.go.dev 网页取元数据的工具，可以换成这些端点；碰到包路径歧义时不要自己猜最长路径，按返回的候选显式带上 module 再请求。

来源：https://go.dev/blog/pkgsite-api