Go private module 下载提示 404 时怎么配置 GOPRIVATE

如果 go get 私有模块时看到 https://proxy.golang.org/...: 404 Not Found，先不要清空模块缓存。最常见的原因是 Go 还把这个模块当成公共依赖，仍在访问公开代理和校验数据库。给真实的 module path 配置 GOPRIVATE 后，匹配的私有模块会避开公共默认路径；如果团队有企业模块代理，再用 GONOPROXY 做更细的覆盖。

直连私有仓库时，先设置 GOPRIVATE=私有模块前缀；使用企业代理时保留 GOPRIVATE，再设置 GONOPROXY=none 让下载回到企业 GOPROXY。如果配置后仍是 404，重点检查 module path、代理返回值和仓库权限，而不是继续改同义的环境变量。

先判断 404 出现在哪一层

把报错里的模块路径与依赖仓库的 go.mod 对照。假设业务代码导入的是 corp.example.com/platform/logkit，仓库中的声明也必须以这个路径为根；如果仓库实际声明成了别的 module path，环境变量命中了也无法修复路径不一致。

还要看 404 的来源。proxy.golang.org 返回 404，通常表示公共代理找不到私有模块；企业代理返回 404，则可能是代理没有同步版本、没有配置该命名空间，或者它故意把“无权访问”隐藏成 404。401/403 更像凭据或授权问题，不能靠 GOPRIVATE 绕过。

GOPRIVATE 到底改变了哪两条下载路径

GOPRIVATE 是一组以逗号分隔的 glob 前缀。它默认同时参与两项判断：私有模块不走公共模块代理，也不向公共 checksum 数据库查询。常见的个人或直连仓库配置可以这样写：

# 按真实 module path 前缀填写，不要写本地目录名
go env -w GOPRIVATE=corp.example.com,github.com/acme/private

# 查看当前 Go 命令实际会读取的值
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB

这不是把所有依赖都切到直连。公共模块仍可使用默认的 GOPROXY；只有匹配私有前缀的模块改变路径。*.corp.example.com 适合覆盖多个子域，corp.example.com/team 则更窄，便于只保护一个命名空间。

直连私有仓库与企业代理要分开配置

如果公司没有模块代理，通常让匹配的模块走版本控制仓库，并单独配置 Git 或其他 VCS 的凭据。此时不要把访问令牌写进文章、脚本或 go env 的可共享配置中；凭据应由 CI 密钥或本机凭据助手提供。

如果公司已经部署了模块代理，目标就不是“绕开所有代理”，而是让私有模块进入指定的企业代理。官方文档给出的覆盖思路是：GOPRIVATE 继续表达隐私范围，GONOPROXY=none 覆盖它对代理选择的默认影响：

# 私有模块仍不应访问公共 checksum 数据库
go env -w GOPRIVATE=*.corp.example.com

# 让企业代理承接公共和私有模块；逗号表示仅在 404/410 时回退
go env -w GOPROXY=https://proxy.corp.example.com,direct

# none 不匹配任何模块，从而覆盖 GOPRIVATE 对“是否走代理”的默认决定
go env -w GONOPROXY=none

这里的 direct 不是认证配置，也不是保证一定成功的兜底。企业代理若返回 401/403，Go 不会把它当成普通缺失版本；若代理返回 404，逗号分隔的下一个来源才有机会被尝试。是否需要 GONOSUMDB=none，取决于企业代理是否提供你们认可的校验服务；不要为了消除错误而全局设置 GOSUMDB=off。

用最小验证命令定位剩余问题

配置后先确认变量值，再只下载一个已知私有模块。不要一上来执行全量 go mod tidy，否则公共依赖、测试依赖和私有依赖混在一起，错误来源不容易判断。

# 先确认命中规则和代理顺序
go env GOPRIVATE GOPROXY GONOPROXY GONOSUMDB

# 只验证一个私有模块；版本替换成仓库实际存在的版本
go mod download corp.example.com/platform/logkit@v1.4.2

# 若仍失败，查看模块声明和当前主模块边界
go list -m -json corp.example.com/platform/logkit

常见问题

GOPRIVATE 要写仓库地址还是 import path？

写 Go 使用的 module path 前缀，例如 github.com/acme/private 或 *.corp.example.com，不要写带用户名的网页地址或本地文件路径。

设置 GOPRIVATE 后还需要 GONOSUMDB 吗？

多数场景不需要。GONOSUMDB 用来单独覆盖校验数据库判断，只有下载路径和校验路径需要不同策略时才单独设置。

为什么配了 GOPRIVATE 仍然 404？

常见原因是模式没有匹配、仓库的 module path 不一致、请求的版本不存在、企业代理未同步，或凭据被代理隐藏成 404。先确认错误来源，再按最小下载命令逐层排查。