查询私有模块时 pkg.go.dev API 为什么找不到包

本地可以 go get 私有模块，调用 pkg.go.dev API 却返回 not found，通常不是令牌失效，也不是 GOPRIVATE 没生效。直接原因是：pkg.go.dev 是面向公共 Go 模块数据的服务，它不会继承调用方电脑上的 Git 凭据、企业网络权限或 GOPRIVATE 配置。

官方说明显示，pkg.go.dev 的站点数据从 proxy.golang.org 下载，并通过 index.golang.org 发现新版本。私有模块本来就不应该进入这些公共基础设施，因此公共 API 没有对应记录是符合预期的结果。

官方 API 文档：https://pkg.go.dev/v1/api

公共 API 与私有模块之间隔着什么

需要先把两个执行主体分开：你的 go 命令运行在本地或企业 CI 中，可以使用内部 DNS、Git 配置、SSH 密钥、凭据助手和企业代理；pkg.go.dev 则运行在公共服务端，只能查询它已经收录的数据。两者都处理 Go 模块，但权限边界完全不同。

因此，给 pkg.go.dev API 请求增加企业仓库的 Authorization 头并不是正确方案。当前 API 文档描述的是 GET-only JSON 查询接口，没有把调用方凭据转发到任意私有仓库的机制。把私库令牌发给公共域名还会扩大凭据暴露面。

GOPRIVATE 到底改变了什么

GOPRIVATE 是 go 命令的环境配置。匹配该变量的模块会默认绕过公共模块代理和公共校验数据库，转而按本地环境配置访问版本控制系统。它解决的是“本地 go 命令应该去哪取私有模块”，而不是“让 pkg.go.dev 收录私有模块”。

# 把企业模块前缀标记为私有，避免把路径发送给公共代理和校验库
go env -w GOPRIVATE='git.example.com/team/*'

# 在已经配置好企业 Git 凭据的环境中确认模块是否可解析
go list -m -json git.example.com/team/secret@latest

# 从当前项目的实际模块图中核对依赖版本
go list -m -json all

# 在本地源码和依赖缓存中查看包文档
go doc git.example.com/team/secret/pkg

如果第一条 go list 仍失败，应该排查企业仓库地址、模块路径、标签、网络和 VCS 凭据。即使这些问题全部修复，pkg.go.dev API 对该私有路径仍可能继续返回 not found，因为公共服务的数据边界并未改变。

not found 不只有一种原因

不能看到 404 就立即下结论。相同表象至少对应四类原因，排查入口也不同。

API 还存在一种容易混淆的情况：同一个 package path 可能由多个 module 提供。当前文档说明，这时错误响应会给出 candidates，调用方应通过 module 参数消除歧义。它属于定位问题，不等于私有模块不可访问。

私有模块应该怎么查

方案一：直接访问私有仓库

团队规模较小或已有统一 Git 凭据管理时，可以让 go 命令直接访问私有仓库。GOPRIVATE 负责声明私有前缀，真正的认证仍由 Git、SSH、凭据助手或 Go 的认证配置完成。

# 查看当前私有模块和代理配置，避免在日志中打印任何秘密值
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB

# 在项目目录解析全部包，暴露路径、标签和构建约束问题
go list -deps -json ./...

# 只列出当前项目实际选择的模块版本
go list -m -f '{{.Path}} {{.Version}}' all

不要把用户名、密码或令牌直接写进示例命令、仓库 URL 和可共享日志。官方模块参考还提醒，凭据出现在环境变量 URL 中可能被 shell 历史或日志记录；生产环境应采用受控的凭据管理方式。

方案二：使用企业私有模块代理

依赖多、构建节点多时，企业可以部署私有模块代理。此时 GOPROXY 先指向企业代理，再按策略回退到公共代理；私有前缀应通过 GONOSUMDB 避免查询公共校验数据库。

# 企业代理优先，404 或 410 时再尝试公共代理与直连
go env -w GOPROXY='https://proxy.corp.example.com,https://proxy.golang.org,direct'

# 私有模块不向公共校验数据库查询
go env -w GONOSUMDB='git.example.com/team/*'

# 用企业代理环境核对目标模块元数据
go list -m -json git.example.com/team/secret@latest

这套配置与“直接访问私库”的配置目标不同，不应机械叠加。GOPRIVATE 会作为 GONOPROXY 和 GONOSUMDB 的默认值；如果希望私有模块经过企业代理，就要明确设计 GONOPROXY 策略，避免它们被本地 go 命令直接绕过。

公共模块未收录时再考虑请求收录

pkg.go.dev 的 About 页面说明，站点从公共模块镜像获取数据，并监控 Go Module Index。对于确认公开的模块，可以访问对应 pkg.go.dev 页面请求添加，或让公共模块代理获取该版本。新版本通常会随后被索引。

这个做法绝不能套用到私有模块。尤其不要为了“触发收录”而请求 proxy.golang.org/私有路径。Go 模块参考指出，公共代理请求会携带完整模块路径；正确配置 GOPRIVATE 的目的之一，就是避免私有路径泄露给公共服务。

查询公共包时应补齐精确参数

确认目标是公开模块后，再检查 API 请求本身。package 路由支持 module、version、goos 和 goarch。省略 version 时选择 latest；省略构建上下文时使用默认文档上下文，通常为 linux/amd64。

# 用 module 和 version 固定包的提供方与版本
curl -L 'https://pkg.go.dev/v1/package/golang.org/x/time/rate?module=golang.org/x/time&version=v0.16.0'

# 平台相关包显式指定文档构建上下文
curl -L 'https://pkg.go.dev/v1/package/example.com/public/windowsdriver?module=example.com/public&version=latest&goos=windows&goarch=amd64'

如果响应给出 candidates，从项目的 go.mod 或 go list -m all 中取得实际 module path，再带着 module 重试。不要把候选数组第一项当成默认答案。

最终采用建议

• 查公共生态元数据：使用 pkg.go.dev API，并传入精确的 module、version 与构建上下文。
• 查私有模块依赖：在已授权的本地或 CI 环境运行 go list，不要等待 pkg.go.dev 收录。
• 查私有包文档：在内部源码或模块缓存上使用 go doc，或建设受控的内部文档索引。
• 统一企业下载入口：部署私有模块代理，并明确 GOPROXY、GONOPROXY 与 GONOSUMDB 的组合策略。
• 看到 not found：先判断访问边界，再检查收录状态、路径版本和 GOOS/GOARCH。

常见问题

本地设置 GOPRIVATE 后，pkg.go.dev API 为什么还是 404？

因为 GOPRIVATE 只影响运行该配置的 go 命令。pkg.go.dev 服务端看不到你的本地环境变量，也不会获得私有仓库权限。

能否把 Git Token 放进 pkg.go.dev 请求头？

不能把它当作私有模块查询方案。当前公共 API 没有接收任意仓库凭据并代为读取私库的接口，而且向公共服务发送企业令牌会增加安全风险。

私有模块怎样生成与公共包类似的文档？

最简单的入口是已授权环境中的 go doc。团队需要搜索、版本与权限控制时，可以在企业网络内建设文档索引，但数据源、凭据和访问日志都应留在受控边界内。

公共模块也查不到时，先看什么？

依次核对 module path、主版本后缀、version、package 子目录、是否被公共镜像收录，以及 GOOS/GOARCH。若 API 返回 candidates，应显式补 module，而不是继续修改 GOPRIVATE。

归根结底，not found 是“公共服务没有这条可查询记录”，不等于“你的私有模块不存在”。先确认数据边界，再选择公共 API 或企业内部工具，排查会快很多，也更安全。