必须显式配置GOPRIVATE才能拉取私有模块，否则Go默认走GOPROXY导致认证失败或404；同时需配对GOSUMDB=off或私有sumdb，并在GOPROXY末尾添加,direct以直连私有源。
私有模块拉取失败：GOPRIVATE 必须显式配置
Go 默认把所有模块都当作公共模块处理，哪怕你用的是公司内网 Git 地址（如 gitlab.internal.company/project），只要没告诉 Go “这是私有的”，它就会走 GOPROXY，然后因认证失败或 404 报错。这不是代理配错了，是根本没进私有通道。
必须设置 GOPRIVATE，且值要精确匹配域名或通配符：
-
go env -w GOPRIVATE=gitlab.internal.company（单域名） -
go env -w GOPRIVATE="*.internal.company,github.com/my-org"（支持通配符和多个，用英文逗号分隔） - 若用 SSH 地址（如
git@gitlab.internal.company:proj/repo.git），Go 会自动转成 HTTPS 形式校验，所以GOPRIVATE仍需填域名部分
验证方式：运行 go env GOPRIVATE，输出应非空；再试 go list -m private-module@v1.2.3，不报 Get "https://proxy.golang.org/..." 就说明已绕过代理。
checksum mismatch 错误：别删 go.sum，先查 GOSUMDB 和 GOPRIVATE
报 verifying github.com/xxx@v1.2.3: checksum mismatch 时，90% 不是包被篡改，而是 Go 拿错了校验源——它试图从 sum.golang.org 查哈希，但该服务无法访问私有模块，或你没设 GOPRIVATE，导致 Go 用代理下载的 zip 和官方索引对不上。
立即学习“go语言免费学习笔记（深入）”；
正确做法是：
- 确认
GOPRIVATE已包含对应域名（否则 Go 强制走GOSUMDB校验） - 检查
GOSUMDB是否为默认值sum.golang.org；私有场景可设为off或指向内部校验服务：go env -w GOSUMDB=off - 若用自建私有代理（如 Athens），应同步部署
sumdb服务，或让代理返回正确的.mod和.zip哈希
注意：go clean -modcache 只清本地缓存，不解决校验源错配；go mod download -dirty 是重建哈希快照的补救命令，但前提是 GOPRIVATE 和 GOSUMDB 已配对。
离线编译私有模块：go mod download -json 输出可重放
CI/CD 或生产环境无外网时，不能靠 go build 实时拉依赖。必须提前把所有模块（含私有模块）完整下载并固化路径。
关键不是“下载完就行”，而是确保可复现：
- 在干净环境（如 Docker 容器）中执行：
go mod download -json > deps.json，该输出含每个模块的Path、Version、Sum和Dir - 用
go mod download -o ./vendor.zip all打包全部依赖（Go 1.21+ 支持），解压后可通过GO111MODULE=on GOPATH=none GOPROXY=file://$(pwd)/vendor.zip go build离线构建 - 若私有模块托管在 Git，需提前用
git archive或go mod vendor导出，并在go.mod中用replace指向本地路径（上线前务必移除replace，否则go.sum记录的是原始模块哈希）
私有代理 + 安全校验共存：direct 后缀不能少
国内镜像如 https://goproxy.cn 虽快，但若只设 GOPROXY=https://goproxy.cn，所有请求（包括私有模块）都会发给它，必然失败。必须加 ,direct 显式声明 fallback 行为。
推荐写法：
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,direct-
direct不是可选项，是 Go 的保留字，表示“不走代理，直连源地址” - 多个镜像用英文逗号分隔，Go 会按序尝试，任一成功即停止；
direct必须放在最后，否则私有模块永远走不到
容易忽略的点：Windows 用户用 setx 设置环境变量时，direct 后不能有空格，否则 Go 解析失败，表现为私有模块仍走代理并超时。
