GOPROXY 私有模块下载返回 404 的配置修复

私有模块下载遇到 404 Not Found 时，先不要把它当成“仓库不存在”。在 Go Modules 中，404 可能只是当前代理没有收录该模块，随后仍会按 GOPROXY 的顺序尝试下一个来源；真正需要修复的是私有模块路径与下载策略没有对齐。

官方地址：https://go.dev/ref/mod#private-modules

本文只处理一个边界：私有模块路径例如 git.corp.example.com/team/shared 下载返回 404。你可以选择让 Go 直连版本控制仓库，也可以让它固定使用内部模块代理；两套配置不要混写成“看起来都对”的组合。

1. 先确认 404 来自哪一层

Go 会按照 GOPROXY 中的来源顺序查询模块。使用逗号分隔时，当前来源返回 404 或 410 才会继续回退；如果返回 403、500 等其他错误，后面的来源不会按同样规则接管。因此“内部代理返回 404”与“内部代理拒绝访问”是两条不同的排查路径。

2. 先决定是直连仓库还是走内部代理

没有私有模块代理时，最小配置通常是把私有模块前缀交给 GOPRIVATE。它会作为 GONOPROXY 和 GONOSUMDB 的默认值，让匹配的模块绕过公共代理和公共校验数据库：

# 把公司模块前缀标记为私有，避免请求公共代理和校验库。
go env -w GOPRIVATE=git.corp.example.com

# 读取当前 Go 进程将使用的配置，确认没有被其他环境变量覆盖。
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB

如果组织有一个专门提供私有模块的代理，目标就不同了：私有模块仍然应该进内部代理，而不是被 GOPRIVATE 的默认 GONOPROXY 规则直接绕过。这时可以显式写出：

# 私有代理优先，公共模块仍可按 404/410 回退到公共镜像。
go env -w GOPROXY=https://proxy.corp.example.com,https://proxy.golang.org,direct

# 保留私有模块的校验例外，但允许它们使用内部代理。
go env -w GOPRIVATE=git.corp.example.com
go env -w GONOPROXY=none
go env -w GONOSUMDB=git.corp.example.com

这里的关键不是把每个变量都填上，而是先回答“私有模块由谁下载”。直连方案依赖 VCS 仓库可访问；代理方案依赖内部代理能按 GOPROXY 协议提供模块元数据和压缩包。

3. 让路径匹配和代理回退保持一致

GOPRIVATE 使用 path.Match 风格的 glob 前缀规则。配置 git.corp.example.com 后，像 git.corp.example.com/team/shared 这样的子路径会被视为私有；如果实际模块前缀是另一套域名，变量写得再完整也不会命中。

常见的错误组合是：

# 这个组合会让匹配 GOPRIVATE 的模块默认绕过所有代理。
GOPRIVATE=git.corp.example.com
GOPROXY=https://proxy.corp.example.com,direct

如果内部代理正是私有模块的来源，上面的配置可能导致 Go 直接访问仓库，最终把问题从“代理 404”变成“仓库认证失败”。应改成上一节的 GONOPROXY=none，或者改用更精细的 GONOSUMDB 来单独表达校验库例外。

反过来，如果内部代理只服务私有模块，使用逗号列表时它返回 404，Go 可以继续尝试公共代理和 direct。如果代理用 403 表示“没有权限”，则应先修代理权限；把 403 当成“模块不存在”会掩盖真正的访问控制问题。

4. 用最小下载检查配置是否生效

先回显环境，再针对一个明确版本执行最小下载。下面命令只用于检查当前配置读取到的值；它不是清缓存或重复执行下载的万能修复。

# 先确认模块前缀与代理策略，再下载一个明确版本。
go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB
go mod download git.corp.example.com/team/shared@v1.2.3

如果仍然是 404，按顺序看三件事：模块路径是否与 go.mod 中的 module 行一致；内部代理是否真的发布了该版本的 .mod、.info 和 .zip；如果进入直连，仓库是否能被当前 Git 凭据读取。不要只重复执行 go get，因为它不会修正错误的路径匹配。

如果错误从 404 变成 403，说明请求已经到达某个代理或仓库，下一步应查权限；如果变成找不到 go-import 元信息，说明直连阶段的仓库根路径解析还没有完成。错误类型发生变化本身就是定位线索。

5. 相关问题与适用边界

为什么设置了 GOPRIVATE，私有模块仍然访问公共代理？先确认当前 Go 进程读取到的值，再确认 glob 前缀是否覆盖真实模块路径；不要只看 shell 配置文件，go env -w 和进程环境也可能共同影响结果。

内部代理已经能提供私有模块，还需要 GONOPROXY=none 吗？如果使用 GOPRIVATE 且希望匹配的私有模块继续走内部代理，建议显式设置 GONOPROXY=none，把“是否走代理”和“是否使用公共校验库”分开表达。

404 后为什么没有继续 direct？检查 GOPROXY 是否使用逗号、代理是否返回了 404/410，以及模块路径是否已经被其他变量规则改成直连或禁用。真正的修复点是让模块归属、代理顺序和错误码语义一致。