go mod init 后依赖拉不下来，首要排查 GOPROXY 是否生效；若 go mod tidy 卡住或报 i/o timeout，大概率是 GOPROXY 未正确配置，需执行 go env GOPROXY 确认输出为 https://goproxy.cn,https://mirrors.tuna.tsinghua.edu.cn/goproxy/,direct 且无空格、中文逗号或大小写错误。
go mod init 之后依赖拉不下来，先查 GOPROXY 是否生效
直接执行 go mod tidy 卡住或报 dial tcp 216.239.37.1:443: i/o timeout，基本就是 GOPROXY 没起作用。Go 1.13+ 默认启用模块代理，但不会自动 fallback 到国内镜像——你得自己配。
验证方式很简单：
- 运行
go env GOPROXY，确认输出不是空或默认的https://proxy.golang.org,direct - 检查是否用了中文逗号、空格或大小写错误（比如写成
DIRECT或https://goproxy.cn , direct） - 如果用
go env -w设置过，注意它写入的是用户级配置；CI 环境或 Docker 容器里得显式 export
推荐值（2026 年实测稳定）：https://goproxy.cn,https://mirrors.tuna.tsinghua.edu.cn/goproxy/,direct。清华源支持元数据查询，七牛源同步快，direct 是兜底项，小写、无协议、无空格。
私有模块被代理拦截，必须配 GOPRIVATE
公司内网 Git（如 git.internal.company.com/mylib）一旦出现在 go.mod 里，Go 默认仍会尝试走 GOPROXY，结果要么超时，要么返回 404。这不是网络问题，是策略问题。
立即学习“go语言免费学习笔记（深入）”；
GOPRIVATE 的作用是告诉 Go：“这些前缀的模块，别转发给代理，也别去 sum.golang.org 校验”。设置时注意：
- 用逗号分隔多个域名，支持通配符：
go env -w GOPRIVATE="git.internal.company.com,github.com/myorg/*" - 如果私有库用 HTTP（非 HTTPS），还得加
GOINSECURE=git.internal.company.com -
GOPRIVATE不影响go.sum生成——私有模块的 checksum 仍会记录，只是跳过远程校验
漏配 GOPRIVATE 的典型现象：go get 成功但 go build 报 checksum mismatch，因为构建时又去查了 sumdb。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
微服务间模块版本冲突，靠 replace + require 组合解耦
当多个微服务共用一个内部 SDK 模块（如 internal/pkg/auth），各服务各自升级会导致 go.sum 不一致、CI 构建失败。硬性要求所有服务同步升级不现实，需要用 replace 隔离本地开发与发布版本。
操作要点：
- 在主服务的
go.mod里写：replace internal/pkg/auth => ../auth（指向本地路径），仅用于开发调试 - 上线前删掉
replace行，并确保require internal/pkg/auth v0.3.1显式声明版本 - 禁止在
replace中使用github.com/user/repo@commit这类 commit-hash 形式——它绕过版本解析，会让go list -m all失效，CI 无法感知真实依赖树
更稳妥的做法是：SDK 发布带 tag 的语义化版本（v0.3.1），各服务通过 go get internal/pkg/auth@v0.3.1 显式升级，而非依赖间接传递。
GOSUMDB 被墙导致 checksum mismatch，不能简单关掉
看到 verifying github.com/some/pkg@v1.2.3: checksum mismatch，第一反应常是设 GOSUMDB=off。这等于拆掉安全气囊——后续任何中间人攻击或仓库篡改都不可知。
真正该做的是：
- 优先换用支持 sumdb 代理的镜像，比如
goproxy.cn自带sum.golang.org代理能力，配好GOPROXY后GOSUMDB可保持默认 - 若必须绕过校验（仅限完全可信的内网环境），用
GONOSUMDB=git.internal.company.com替代全局off，精准控制范围 -
go clean -modcache后再go mod download，避免旧缓存干扰校验
容易忽略的一点：go.sum 文件本身是项目契约，它和 go.mod 一样必须提交。删掉它或忽略它，等于放弃构建一致性保障。
