go mod download应置于copy go.mod和go.sum之后、copy . .之前，以复用缓存；多阶段构建中需在builder阶段显式设置env goproxy和goprivate，否则代理不生效。
go mod download 放在 COPY 之前才能复用缓存
很多 Dockerfile 把 go mod download 写在 COPY . . 之后，导致每次代码变更都会让这层失效——Docker 缓存从那一行起全部重建，依赖又得重下一遍。
真正有效的顺序是：
- 先
COPY go.mod go.sum .（只复制这两个文件） - 紧接着执行
go mod download - 最后
COPY . .复制全部源码
这样只要 go.mod 或 go.sum 没变，go mod download 这一层就永远命中缓存。实测 CI 中依赖下载时间从 40+ 秒降到 0.3 秒以内。
多阶段构建中 build-stage 的 GOPROXY 必须显式继承
在 multi-stage Dockerfile 里，build-stage 默认不继承宿主机环境变量，go mod download 仍会打向 proxy.golang.org，卡住或超时。
必须显式设置代理：
- 用
ENV GOPROXY=https://goproxy.cn,direct（不是靠宿主机 export） - 避免写成
ARG GOPROXY后再ENV赋值——ARG 在 FROM 之后的 stage 里默认为空 - 如果公司有内网 Nexus，优先放前面：
ENV GOPROXY=http://nexus.internal/repository/goproxy/,https://goproxy.cn,direct
验证方式：在 build-stage 加一句 go env GOPROXY，输出必须是你设的值，而不是空或默认地址。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
go mod download -x 能暴露真实请求路径，别只信 go env
go env GOPROXY 显示正确 ≠ 实际生效。常见陷阱是 shell 启动新进程时没传环境变量，或者被 CI runner 的默认环境覆盖。
最可靠验证法：
- 在构建命令中加
-x参数：go mod download -x github.com/go-sql-driver/mysql@v1.14.0 - 观察输出里是否出现
GET https://goproxy.cn/... - 如果看到
GET https://proxy.golang.org/...或直接git clone，说明代理完全没走通
此时要检查：Dockerfile 中 ENV 是否写对位置、CI 配置是否清除了环境变量、有没有其他脚本在构建前 unset 了 GOPROXY。
GOPRIVATE 必须匹配私有模块路径，否则 fallback 失效
当 go.mod 里有类似 replace git.example.com/internal => ./internal 或引用内网 Git 地址时，如果 GOPRIVATE 没配对，Go 仍会尝试把该模块发给代理，结果 404 或超时。
配置要点：
-
ENV GOPRIVATE=git.example.com/internal,git.example.com/lib（逗号分隔，不带通配符*也能匹配子路径） - 不要写成
git.example.com/*—— Go 1.19+ 要求显式列出或用**，但多数 CI 环境用旧版 Go，稳妥起见列明具体域名/路径 - 如果用了
replace指向本地路径（如./internal），GOPRIVATE不影响它，但得确保COPY顺序让./internal在go mod download前就存在
最容易被忽略的是：私有模块路径大小写、端口（如 :8080）、协议前缀（ssh:// vs https://）都必须和 GOPRIVATE 完全一致，否则 fallback 直连逻辑不会触发。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
