go mod download 在 Jenkins 中常因共享出口 IP 触发代理限流（429）或超时，根本原因是缓存未复用、GOPROXY 配置不当及 workspace 清空导致重复下载；需持久化 $GOPATH/pkg/mod 和 $GOCACHE、显式设置 GOPROXY=https://goproxy.cn,direct、禁用 GOSUMDB（内网可信环境），并避免仅依赖 go build -mod=readonly。
为什么 go mod download 在 Jenkins 里总被限流或超时
Go 模块代理（如 proxy.golang.org）对未认证的 IP 有明确的请求频次限制，而 Jenkins 节点通常共享出口 IP，尤其在并行构建多项目时，go mod download 会高频触发模块拉取，极易触发 429 Too Many Requests 或连接超时。这不是 Go 本身的问题，而是代理策略与 CI 环境不匹配导致的。
关键点在于：Jenkins 每次构建默认清空工作区或使用全新 workspace，go mod download 就得重下所有模块——哪怕上一次刚下完。缓存没被复用，请求量翻倍。
- 确保
GOPROXY显式设为支持缓存的地址（如https://goproxy.cn,direct或自建athens），避免 fallback 到官方代理 - 禁用
GOSUMDB=off（仅限可信内网环境），否则每次校验都会额外发起网络请求 - 在 Jenkins agent 的全局环境变量中预设
GOPATH和GOCACHE，指向持久化路径（如/var/jenkins_home/go-cache），而非默认的$HOME
如何让 go mod download 复用已有模块缓存
Jenkins 默认不保留 $GOPATH/pkg/mod，所以必须显式挂载或复用模块缓存目录。不能只靠 go build -mod=readonly，它不解决下载阶段的重复拉取。
- 在 Jenkinsfile 中用
dir指向固定模块缓存路径：dir('/var/jenkins_home/go-mod-cache') { sh 'go mod download' } - 更稳妥的方式是配合
go env -w GOPATH=/var/jenkins_home/go，再让go mod download自动写入/var/jenkins_home/go/pkg/mod - 如果用 Docker agent，需通过
volumes挂载宿主机缓存目录，且确保容器内用户有写权限（UID 匹配）
自建代理（如 Athens）是否必要？什么情况下值得上
不是所有团队都需要自建代理，但以下情况建议上：go proxy 响应慢、依赖私有模块（gitlab.example.com/internal/lib）、审计要求模块二进制留存、或 Jenkins 构建节点无外网权限。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- Athens 支持
GO_PROXY协议，配置简单，可部署在内网 Kubernetes 或单机，存储后端可用本地磁盘或 S3 - 关键配置项：
ATHENS_DISK_STORAGE_ROOT（缓存路径）、ATHENS_GO_BINARY_PATH（指定 go 版本）、ATHENS_RATE_LIMIT_MAX（默认不限，无需调） - 注意：Athens 不会自动同步私有模块，首次拉取仍需 git 凭据（如
~/.netrc或git config --global url."https://token:x-oauth-basic@github.com".insteadOf "https://github.com"）
go mod vendor 是救急方案，但别当长期解法
把模块打进代码仓库（vendor/）确实能彻底离线构建，但它放大了 Git 仓库体积、增加 PR 审查负担、且容易因忘记更新 vendor 导致线上行为不一致。
- 仅建议用于：严格离线环境、安全扫描强制要求模块源码可见、或临时绕过代理故障
- 执行前务必确认
GO111MODULE=on，且go mod vendor后检查vendor/modules.txt是否完整 - Jenkinsfile 中应加校验：
sh 'go mod vendor && git diff --quiet vendor || (echo "vendor out of sync"; exit 1)'
最常被忽略的是 GOPROXY 的 fallback 行为：逗号分隔列表中只要有一个代理返回 404，就会继续试下一个；但如果第一个返回 429，整个链就断了——所以顺序和健康检查比单纯多配几个代理更重要。
