重复拉取依赖的根本原因是go工具链未能复用已有模块，主因包括goproxy未正确配置（须设为https://goproxy.cn,direct）、ci中未持久化$gopath/pkg/mod目录、go build触发边编译边拉取导致网络失败重试，以及go.sum不一致引发校验失败回退下载。
重复拉取依赖的根本原因不是“没缓存”，而是 Go 工具链没能复用已有模块——要么缓存路径被忽略，要么代理/环境配置导致每次走网络。解决它不靠技巧，靠明确控制 GOPROXY、go mod download 执行时机和缓存目录生命周期。
确保 GOPROXY 正确启用且包含 direct
Go 默认用 https://proxy.golang.org，但在国内常超时或返回 403，触发 fallback 到 direct 模式（即直连 GitHub 等源），而 direct 没有 CDN 加速，也容易因网络抖动重试拉取。
- 必须显式设置为可信镜像 +
direct：执行go env -w GOPROXY=https://goproxy.cn,direct -
direct不是可选后缀，它是关键开关：对私有域名（如git.company.com/mylib）跳过代理，避免认证失败或证书错误导致反复重试 - 验证是否生效：
go env GOPROXY输出应严格匹配设置值，不能是空或off - CI/CD 中禁止用临时
export GOPROXY=...，要用go env -w写入配置，否则go mod tidy可能仍走默认代理
用 go mod download 预加载，而非等 go build 触发
go build 或 go test 过程中首次遇到未缓存模块时，会边编译边拉取，此时若网络波动或模块发布页变更（如 tag 删除），就可能中断并重试——看起来像“重复拉取”，实则是失败重试。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 在代码复制进容器前，先执行
go mod download：它只读go.mod，批量下载所有依赖到$GOPATH/pkg/mod/cache/download和$GOPATH/pkg/mod - Dockerfile 中顺序必须是：COPY go.mod go.sum → RUN go mod download → COPY . .，否则缓存层失效
- 不要用
go get替代go mod download：前者会修改go.mod，可能引入非预期版本；后者纯下载，安全可控 - CI 中可加
go list -m all | wc -l校验依赖总数，避免因go.mod不完整导致漏下模块
持久化 $GOPATH/pkg/mod 目录，别让它每次清空
Go 的本地缓存本质是磁盘文件，$GOPATH/pkg/mod 存解压后的模块树，$GOPATH/pkg/mod/cache/download 存原始 zip 包。只要这两个目录存在且权限正常，go build 就不会发起任何 HTTP 请求。
- 在 CI/CD 中，把
$GOPATH/pkg/mod设为缓存目录（如 GitHub Actions 的actions/cache缓存~/go/pkg/mod） - Docker 构建时，不要 COPY 宿主机的
~/go/pkg/mod到容器内/go/pkg/mod：宿主机路径 ≠ 容器内$GOPATH，大概率路径错导致缓存失效 - 避免误执行
go clean -modcache：它会删光所有缓存，下次构建必然全量重拉；仅在调试代理问题或确认干净环境时使用 - 多项目共用同一
$GOPATH时，pkg/mod是共享的，无需重复下载——但要注意不同项目用不同 Go 版本时，缓存兼容性无保障
检查 go.sum 是否一致，防止校验失败回退拉取
当 go build 发现某个模块的 hash 与 go.sum 不符，会拒绝使用本地缓存，转而重新下载远程包再校验——这表现为“明明缓存存在却还拉取”。
-
go.sum必须提交到 Git：它不是辅助文件，而是模块完整性凭证 - 团队必须共用同一
GOPROXY设置：如果 A 用goproxy.cn、B 用proxy.golang.org，同一模块可能生成不同 hash（因代理返回的 zip 包 checksum 不同） - 私有模块需配置
GOPRIVATE：例如go env -w GOPRIVATE=git.company.com/*，否则 Go 会尝试走代理，失败后 fallback 到 direct，可能触发重复拉取 - 若发现
go.sum被意外修改，用go mod verify检查一致性，再go mod tidy -v重建校验和
真正难处理的不是“怎么缓存”，而是缓存被悄悄绕过：代理配置错、go.sum 不统一、Docker 层顺序颠倒、CI 环境变量未持久化——这些地方出问题，go mod download 再规范也没用。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
