最稳的gomodcache配置是go env -w gomodcache=/path/to/cache，需绝对路径、提前创建目录并确保写权限；goproxy推荐goproxy.cn,direct；私有仓库加goprivate；replace目标必须含go.mod且路径相对；module声明须与仓库url严格一致。
go env -w GOMODCACHE 是最稳的路径配置方式
直接用 go env -w GOMODCACHE=/path/to/cache 设置，比 shell 的 export 或改 ~/.bashrc 更可靠——它写入 $HOME/go/env，所有 Go 命令（包括 sudo -u user go build）都会读取，且不会被新 Shell 覆盖。
常见错误是只在当前终端 export GOMODCACHE，结果 CI 脚本或后台任务跑起来就 fallback 到默认 ~/go/pkg/mod，导致缓存不复用、重复下载。
- 路径必须是绝对路径，不能含
~（go env -w不展开波浪号） - 目标目录需提前
mkdir -p并确保 Go 进程有写权限（尤其多用户或容器环境） - 若同时设了
GOPROXY，GOMODCACHE只管本地存储位置，不影响代理行为
GOPROXY 配置直接影响下载成功率和速度
国内开发不配 GOPROXY 几乎必然卡在 go mod download，不是超时就是 checksum mismatch。推荐组合：https://goproxy.cn,direct ——优先走国内镜像，失败再直连源站。
注意 direct 必须显式写上，否则代理挂掉时 Go 会报错退出，而不是降级；多个代理用英文逗号分隔，中间**不能有空格**。
- 私有 Git 仓库（如 GitLab 内网）要加进
GOPRIVATE，例如go env -w GOPRIVATE=git.example.com/internal/* - 如果公司强制 HTTPS 代理，还需额外设
http_proxy和https_proxy，否则GOPROXY本身连不上 -
GOSUMDB=off仅用于离线调试，生产环境禁用——它会跳过校验，埋下供应链风险
replace 本地路径必须相对 go.mod 且目标含 go.mod
调试私有模块时写 replace github.com/org/lib => ../lib 很常见，但容易漏掉两个硬性条件：路径必须相对于当前 go.mod 所在目录，且 ../lib 目录下**必须存在有效的 go.mod 文件**。
否则 Go 会尝试按 legacy 模式解析，可能报 no required module provides package 或静默加载错误版本。
- 绝对路径也合法，但写成
/home/user/lib而非~/lib（tilde 不展开） -
replace不传播给下游依赖，别人go get你的模块时不会生效 - 临时替换建议用
go mod edit -replace，避免手敲出错；确认后运行go mod tidy同步go.sum
module 路径写错会导致 checksum mismatch
go.mod 第一行的 module 声明不是别名，而是 Go 校验依赖完整性的锚点。比如代码托管在 github.com/yourname/cli，就必须写 module github.com/yourname/cli，写成 module cli 或 module myapp 本地能编译，但别人 go get 时会因 checksum 不匹配失败。
最容易忽略的是私有 Git 服务路径层级，比如 GitLab 地址是 gitlab.com/group/subgroup/tool，漏掉 subgroup 就算 go mod init 成功，后续 go mod tidy 也会在校验阶段崩。
- 从模板项目复制
go.mod时，务必检查并修正module行 - CI 构建前可加一句
go list -m验证模块路径是否与仓库 URL 一致 - 模块路径一旦发布，就不能随意改——改了等于换了个新模块，旧版本无法升级
GOMODCACHE 权限不对 → 下载卡住；GOPROXY 缺 direct → 构建中断；replace 目标没 go.mod → 导入失败；module 名写错 → 别人根本拉不动。每个点都得抠到细节，少一个就可能拖慢整个团队。
