go.mod 中的 module 路径必须严格匹配实际仓库地址，否则会导致 checksum mismatch 或无法找到模块；goproxy 支持逗号分隔的多源回退，私有模块需配合 goprivate 配置才能绕过代理直连，离线环境须设 goproxy=direct 并预加载完整 mod cache。
go.mod 中的 module 路径必须匹配实际仓库地址
模块路径不是别名，而是 Go 依赖解析和校验的唯一依据。比如你的代码托管在 gitlab.example.com/internal/backend，那么 go.mod 里必须写 module gitlab.example.com/internal/backend。写成 example.com/backend 或 backend 都会导致 checksum mismatch 或 could not find module providing package。
常见错误现象：
- 本地
go mod tidy成功，但 CI 上拉取私有模块失败 - 同事
go get报unknown revision，而你本地能通
根本原因是 Go 在校验 go.sum 时，会按 module 声明路径去查远程仓库的 tag/commit，路径不一致就找不到对应 commit hash。
GOPROXY 支持多级 fallback，用逗号分隔
GOPROXY 环境变量支持多个镜像地址，用英文逗号分隔，Go 会按顺序尝试，直到成功或全部失败。国内最常用组合是：
export GOPROXY=https://goproxy.cn,direct
含义是：先走 https://goproxy.cn，如果它返回 404（比如私有模块没被缓存），就退回到 direct（直连原始仓库）。
使用场景：
- 公司有自建私有代理（如 JFrog Artifactory 的 Go 仓库），想优先走内网：
GOPROXY=https://go-proxy.internal,https://goproxy.cn,direct - 某些模块在 goproxy.cn 滞后，需强制直连某仓库：
go env -w GOPRIVATE=gitlab.example.com/internal/*（配合directfallback 才真正生效）
注意：direct 必须显式写出，不能省略；否则所有未命中代理的请求都会直接失败，而不是回退。
私有模块必须配 GOPRIVATE，否则 proxy 会跳过校验
只要模块路径匹配 GOPRIVATE 规则（支持通配符），Go 就不会向任何 GOPROXY 发起请求，也不会查 GOSUMDB，而是直接走 git 协议克隆 —— 这正是访问公司内网 GitLab / GitHub Enterprise 所需的行为。
实操建议：
- 设为
go env -w GOPRIVATE=gitlab.example.com/internal/*,github.company.com/* - 避免写
GOPRIVATE=*，这会让所有模块都绕过校验，丧失 checksum 安全保障 - 若用 SSH 克隆私有库，确保
~/.ssh/config已配好 host 别名和密钥，否则go get会卡在认证环节
容易踩的坑：只配了 GOPROXY 却没配 GOPRIVATE，结果 Go 仍把私有路径发给 goproxy.cn，返回 404 后直接报错，而不是 fallback。
离线环境必须用 GOPROXY=direct + 预下载 cache
没有网络时，go mod download 默认会尝试连接所有 GOPROXY 地址，哪怕已设 https://goproxy.cn,direct，也会先连 goproxy.cn 并超时，浪费数分钟。
正确做法是：
- 联网机器执行：
go mod download -json核对依赖树完整性 - 再执行：
go mod download，它会把所有模块写入$GOPATH/pkg/mod/cache - 打包整个
pkg/mod/cache目录，拷贝到离线机相同路径 - 离线机上必须设：
GOPROXY=direct（不能留逗号分隔的其他地址）
关键点：离线时 direct 不代表“直连网络”，而是“从本地 cache 读取”。如果 cache 缺少某个模块版本，go build 仍会失败 —— 所以预下载必须完整，且 go.sum 必须已提交、未被修改。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
