私有模块拉取失败主因是goproxy与goprivate配置冲突，需确保goprivate仅设私有域名前缀（如git.internal.company.com），goproxy中不得包含其子串，且direct必须置于代理链末尾；同时需配置git凭证或ssh认证，并视情况关闭gosumdb。
私有模块拉取失败时，先确认 GOPROXY 和 GOPRIVATE 是否冲突
常见现象是：公司内部 Git 地址（如 git.internal.company.com）配置了 GOPRIVATE，但 GOPROXY 仍包含该域名，导致 Go 尝试走代理却因认证缺失而失败。Go 的代理逻辑是「先匹配 GOPRIVATE，再 fallback 到 GOPROXY」，所以必须确保两者不重叠。
-
GOPRIVATE应只设为私有域名前缀，例如git.internal.company.com或internal.company.com，不能带协议或路径 -
GOPROXY中的地址不能包含GOPRIVATE中的任何子串，否则会被跳过代理逻辑，但实际又没直连权限，结果卡在 401 或 timeout - 验证方式：运行
go env GOPRIVATE和go env GOPROXY，检查输出是否干净无交集
多级代理链中，direct 必须放在最后，且不能省略
国内常用组合 GOPROXY=https://goproxy.cn,https://goproxy.io,direct 看似简单，但顺序和 direct 的位置直接影响私有模块行为。Go 按逗号分隔顺序逐个尝试代理，遇到第一个返回 200 或 404 的就停止；只有走到 direct 才会放弃代理、改用 git clone 直连。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 如果把
direct放在中间（如https://goproxy.cn,direct,https://goproxy.io），后续镜像永远不生效，且私有模块可能被错误地发往第一个代理 - 多个镜像之间无自动健康检查，靠 HTTP 状态码判断可用性；若第一个镜像临时 503，Go 不会自动切到第二个，除非它返回明确的 404（表示“该模块不存在”）
- 建议固定使用三段式：
主镜像,备用镜像,direct，例如https://goproxy.cn,https://mirrors.aliyun.com/goproxy/,direct
私有模块需配合 git 协议配置与凭证助手
设置了 GOPRIVATE 后，Go 会退回到 git 命令拉取，此时成败取决于本地 git 配置是否支持认证。单纯靠 GOPROXY 无法解决这一层问题。
- 确保
git config --global url."https://token:x-oauth-basic@git.internal.company.com".insteadOf "https://git.internal.company.com"已设置（token 可替换为 SSH key 或 personal access token） - macOS 上推荐启用
git credential-osxkeychain，Linux 推荐git config --global credential.helper store，避免每次拉取都输密码 - 若用 SSH，需确认
git@地址格式已在go.mod中统一，例如replace example.com/internal/pkg => git@git.internal.company.com:team/pkg.git v1.2.0
GOSUMDB=off 是临时方案，不是多级代理的一部分
当私有模块 checksum 校验失败时，有人误以为加一个 https://sum.golang.org 镜像就能解决，其实不行。Go 对私有模块默认禁用 GOSUMDB 校验，但如果 GOPROXY 错误地转发了私有请求，sumdb 可能收到非法索引，反而触发 checksum mismatch。
- 真正安全的做法是：对私有域名显式关 sumdb，例如
go env -w GOSUMDB=off，或更精准地go env -w GOSUMDB=sum.golang.org+insecure（仅限测试环境） - 不要在
GOPROXY链里塞 sumdb 地址——它不是代理，不接受模块下载请求 - 生产环境应维护私有
sum.golang.org兼容服务，或通过go mod verify+ 本地go.sum审计替代全局关闭
GOPRIVATE 范围界定、git 凭据链路打通、以及校验机制的边界控制——这些环节任一出错，都会让看似合理的代理配置完全失效。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
