Go pkg.go.dev API 怎么查询模块的最新稳定版本

如果脚本只需要知道一个 Go 模块当前可用的最新稳定标签，不必抓取 pkg.go.dev 网页。直接请求模块 API：省略 version 时，接口会按模块的最新带标签版本解析，并在响应中给出 version 和 isLatest。

官方地址：https://pkg.go.dev/

本文使用的模块示例是 github.com/google/go-cmp。API 仍处于 /v1beta 路径，生产代码应把路径和版本语义写清楚，不能把网页上显示的“最新”当成无条件的稳定承诺。

选择模块版本接口并理解 latest 默认值

先区分两个任务：要“当前模块是什么版本”，请求 /v1beta/module/{path}；要“有哪些已发布标签”，请求 /v1beta/versions/{path}。前者的响应通常包含 path、version、commitTime、isLatest 和 hasGoMod 等字段。这里的稳定版本判断，应以带标签的语义化版本为主，而不是只看网页排序。

请求地址示例：

# 省略 version，让 API 解析模块的默认最新带标签版本
curl -L "https://pkg.go.dev/v1beta/module/github.com/google/go-cmp"

路径中的斜杠属于模块路径的一部分，实际拼接时不要把它改成查询参数。若代码要处理任意模块名，还要对路径进行 URL 转义，并保留服务器返回的版本字符串。

用 curl 请求模块元数据

调试或在 CI 中做一次轻量检查时，curl 已经够用。推荐先保留原始 JSON，再用 jq 只取判断所需字段：

# 只提取模块路径、解析出的版本和 latest 标记，便于脚本消费
curl -fsSL "https://pkg.go.dev/v1beta/module/github.com/google/go-cmp" \
  | jq '{path, version, isLatest, commitTime, hasGoMod}'

如果输出中的 isLatest 为 true，它说明这次返回的是该模块当前解析结果；真正用于发布清单的版本仍建议保存 version、查询时间和响应状态。接口错误时，-f 会让命令失败，避免把错误 JSON 当成成功版本写入缓存。

在 Go 程序中解析响应

把查询封装成函数时，至少处理 URL 编码、超时、HTTP 状态码和 JSON 解码。下面的示例只读取模块元数据，不把网络结果写进 go.mod，因此适合作为发布检查或依赖报告的一步：

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "time"
)

type moduleInfo struct {
    Path      string `json:"path"`
    Version   string `json:"version"`
    IsLatest  bool   `json:"isLatest"`
    CommitTime string `json:"commitTime"`
}

func latestModule(ctx context.Context, modulePath string) (moduleInfo, error) {
    // PathEscape 防止模块名中的特殊字符破坏请求路径；不传 version 才使用默认 latest。
    endpoint := "https://pkg.go.dev/v1beta/module/" + url.PathEscape(modulePath)
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
    if err != nil {
        return moduleInfo{}, err
    }
    resp, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
    if err != nil {
        return moduleInfo{}, err
    }
    defer resp.Body.Close() // 无论状态码如何都释放连接资源。
    if resp.StatusCode = 300 {
        return moduleInfo{}, fmt.Errorf("pkgsite status: %s", resp.Status)
    }
    var info moduleInfo
    if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
        return moduleInfo{}, err
    }
    return info, nil
}

func main() {
    // 示例只打印可审计字段；生产代码可将它们连同查询时间写入缓存。
    info, err := latestModule(context.Background(), "github.com/google/go-cmp")
    if err != nil {
        panic(err)
    }
    fmt.Printf("%s %s latest=%t\\n", info.Path, info.Version, info.IsLatest)
}

这个函数的关键不是把 API 当成版本安装器，而是把它当成只读元数据服务。网络超时、4xx/5xx 和字段变化都应进入错误路径；不要在失败时默默返回旧版本。

处理指定版本、分支和缓存边界

需要复核历史版本时，可以给支持该参数的接口追加 ?version=v1.2.3。如果要观察默认开发分支，官方 API 支持 main 或 master，但服务会把它解析为对应的伪版本。伪版本能定位提交，却不是正式发布标签。

# 查询一个明确的语义化版本；版本值来自发布标签，不由脚本自行猜测
curl -fsSL "https://pkg.go.dev/v1beta/module/github.com/google/go-cmp?version=v0.7.0"

# 查询默认分支时会得到对应伪版本，不能把它记录成稳定标签
curl -fsSL "https://pkg.go.dev/v1beta/module/github.com/google/go-cmp?version=main"

如果目标是生成升级候选，使用 /v1beta/versions/{path} 获取标签集合，再按 Go 模块版本规则保存结果。缓存可以减少重复请求，但缓存键必须包含模块路径和版本参数；省略版本的结果也要带上抓取时间，否则“latest”会被误当成永不过期。

用版本列表做发布前检查

实际项目里可以把检查拆成三步：第一步请求模块详情并记录 version；第二步请求版本列表，确认目标标签是否存在；第三步把 API 失败、空列表、伪版本和缓存过期分别记为不同状态。这样升级报告能回答“最新标签是什么”，也能解释“为什么某个分支版本没有进入稳定升级清单”。

还要留意模块的主版本路径：example.com/lib/v2 与 example.com/lib 是不同的模块路径，不能只截掉 /v2 再查询。对于模块尚未被 pkg.go.dev 收录的情况，应先按官方说明让模块版本进入代理索引，再重试查询。

相关问题

省略 version 一定返回最新稳定发布版吗？

它返回 API 解析的最新带标签版本；本文把“稳定”限定为可识别的语义化标签，不把 main/master 的伪版本算作稳定发布版。

为什么不直接解析 pkg.go.dev 网页？

网页展示适合人工阅读，API 返回结构化字段，更适合 CI、依赖报告和工具集成，也避免依赖页面排版。

什么时候应该请求 versions 接口？

当你要比较多个标签、检查某个版本是否存在或记录完整发布序列时使用它；只要当前模块元数据时，module 接口更直接。