私有模块拉取失败主因是未配置GOPRIVATE导致请求被代理拦截，应执行go env -w GOPRIVATE="git.company.com,github.com/my-org/"（逗号分隔、无空格、支持通配），并确保GOPROXY以direct结尾、GOSUMDB关闭或替换。
私有模块拉取失败：403 / unknown revision / authentication required
Go 默认会把所有模块请求都转发给 GOPROXY，包括你公司内网的 git.company.com 或 GitHub 私有组织仓库。一旦没加进 GOPRIVATE，代理就会尝试转发——结果不是 403 就是 404，根本不是权限或 token 问题，是路由错位。
- 立即执行：
go env -w GOPRIVATE="git.company.com,github.com/my-org/*"（注意逗号分隔、无空格、支持*通配） - 多个域名用英文逗号拼接，
GOPRIVATE不支持正则，也不接受空格 - 如果用 SSH 克隆，确保
~/.ssh/id_rsa已添加到对应平台；如果用 HTTPS，提前运行git config --global credential.helper store并手动 clone 一次输凭据 - 验证是否生效：
go env GOPRIVATE应输出你刚设的值，不是空
代理 fallback 失效：为什么设置了清华源还是卡住
常见错误是只写了一个代理地址，没加 direct 回退项。Go 的代理链必须以 direct 收尾，否则匹配 GOPRIVATE 的请求仍会尝试走前一个代理，而不是跳过。
- 正确写法：
go env -w GOPROXY="https://mirrors.tuna.tsinghua.edu.cn/go/modules/,https://goproxy.cn,direct" - 顺序很重要：Go 从左到右尝试，遇到第一个能连上的就用；
direct必须在最后，表示“前面都失败就直连” - IDE（如 GoLand、VS Code）可能不读系统 shell 的环境变量——务必在 IDE 内置终端里也执行一遍
go env -w GOPROXY=...，或检查 IDE 的 Go 设置页是否覆盖了该变量 - 临时验证：运行
GOPROXY=direct go mod download -v，如果立刻失败（非卡住），说明是网络或 Git 配置问题；如果仍卡，问题在代理链本身
校验环节中断：checksum mismatch 不是缓存损坏，而是 sum.golang.org 连不上
go mod download 卡在 verifying github.com/xxx@v1.2.3: checksum mismatch，大概率不是模块被篡改，而是 GOSUMDB 默认指向海外服务器，局域网或防火墙环境下根本无法访问。
- 开发/测试环境可临时关闭校验：
go env -w GOSUMDB=off（切勿提交到 CI 或生产环境） - 更稳妥的做法是换校验源：
go env -w GOSUMDB=sum.golang.org+replace=https://goproxy.cn/sumdb（需代理服务支持） - 注意：
GOPROXY=off和GOSUMDB=off必须同时设置，否则即使关了代理，校验步骤仍会触发连接失败 - 若已出现
zip: not a valid zip file报错，说明某模块缓存损坏，直接删掉对应路径即可（如报错含github.com/some/pkg，就删$GOMODCACHE/github.com/some/pkg@v1.2.3）
离线或弱网环境：依赖下载失败不是缺包，是机制强依赖网络
Go 模块机制默认假设网络通畅。go mod download 不是“找本地缓存”，而是联网拉取 + 校验 + 写入缓存。离线机器上，仅拷贝 $GOPATH/pkg/mod 目录是不够的，因为 go.sum 和校验逻辑仍会尝试连接外部服务。
- 离线前提：必须在有网机器上先完成
go mod tidy和go mod download，再用go env GOMODCACHE确认真实路径，打包整个目录 - 离线机上执行：
go env -w GOPROXY=off和go env -w GOSUMDB=off，两者缺一不可 - 确保离线机的
go version与下载机一致，不同版本缓存结构可能不兼容 - 若项目用了
replace指向本地路径，离线时要确认这些路径真实存在且可读
GOPROXY、GOPRIVATE、GOSUMDB 的响应逻辑不一致——比如 go list -m all 可能成功，但 go mod verify 仍失败；又比如 IDE 内置终端和系统终端环境变量不同步。动手前，先跑一遍 go env GOPROXY GOPRIVATE GOSUMDB，眼见为实。 
