go mod tidy或者go build卡住不动，十有八九卡在下载依赖那一步。报错串基本能分成三类：连不上代理、校验不过、配置把下载通道给关了。先把报错原文看清楚再动手，比反复重试快得多。
先确认这台机器到底在用哪套配置：
go version go env GOPROXY GOSUMDB GOPRIVATE GOMODCACHE GOFLAGS
默认值是GOPROXY=https://proxy.golang.org,direct，这个地址在国内多数网络环境下要么超时，要么直接连接被重置。
下载超时：换模块代理
最常见的原文是dial tcp后面跟一个IP和443，末尾i/o timeout，或者干脆长时间停在go: downloading那一行不动。换一个能连上的模块代理就行：
go env -w GOPROXY=https://goproxy.cn,direct
末尾那个direct不能丢。它的意思是镜像上查不到（HTTP 404或410）时回源到版本控制系统去取，私有模块和很新的tag都靠它兜底。写多个用逗号分隔，按顺序试：
go env -w GOPROXY=https://goproxy.cn,https://mirrors.aliyun.com/goproxy/,direct
go env -w会把配置写进go env GOENV指向的那个文件，Linux在~/.config/go/env，Windows在%APPDATA%\go\env，一次设置长期有效。临时换用环境变量即可：GOPROXY=https://goproxy.cn,direct go mod tidy。要撤销写过的配置用go env -u GOPROXY。
校验数据库不用单独改。国内这几个公开镜像都支持代理sumdb的查询请求，换了GOPROXY之后校验也会跟着走镜像，只有镜像本身不支持时才需要把GOSUMDB指定成sum.golang.google.cn。
module lookup disabled by GOPROXY=off
看到这句，说明有人把下载通道显式关掉了：
go: github.com/gin-gonic/gin@v1.9.1: module lookup disabled by GOPROXY=off
见过不少Dockerfile为了"加速构建"直接写ENV GOPROXY=off，结果基础镜像里没有预置的模块缓存，构建第一步就死在这儿。两种正当用法：确实要离线构建，先把依赖打进vendor目录：
go mod vendor go build -mod=vendor ./...
或者明确允许联网，把off改回镜像地址。
missing go.sum entry：不是网络问题
这条报错的原文长这样：
missing go.sum entry for module github.com/gin-gonic/gin; to add it: go mod download github.com/gin-gonic/gin
Go从1.16起把-mod的默认值改成了readonly，go build不再自动帮着改go.mod和go.sum，缺东西就直接报错退出。照提示补上：
go mod download github.com/gin-gonic/gin go mod tidy
老项目从GOPATH模式迁上来时，go.mod里写的go版本偏低也会连带出问题。Go 1.22.0、1.23.0、1.24.0、1.25.0、1.26.0，这几个版本对模块图裁剪的处理并不一样，1.17.0之后的模块只记录直接相关的依赖哈希，跨大版本升级时go.sum经常需要整体重跑一遍tidy。已知的版本是Go 1.26.0发布于2026年2月10日，1.25.0发布于2025年8月12日。
确实需要临时回到"自动补"的行为，用环境变量限定这一次命令即可，别全局写死：
GOFLAGS=-mod=mod go mod tidy
私有模块：用GOPRIVATE，别拿GOSUMDB=off当万能药
公司内部的Git仓库拉不下来，或者报SECURITY ERROR说下载内容与校验数据库记录不一致，正确做法是声明这些路径是私有的：
go env -w GOPRIVATE=git.example.com/*,github.com/mycorp/*
GOPRIVATE是GONOPROXY与GONOSUMDB这两个变量的默认值，一次设置同时解决"不走代理直连Git"和"不送校验数据库比对"两件事。反过来，把GOSUMDB设成off是把所有依赖（包括公开依赖）的透明度日志校验一起关掉，等于把供应链上的一道防线全拆了，属于为了修一个私有模块的问题把整台机器的安全级别降下去。
私有仓库还要能通过HTTPS或SSH取到代码。走SSH的，在~/.gitconfig里加上：
[url "git@git.example.com:"] insteadOf = https://git.example.com/
缓存坏了：checksum mismatch
报verifying module: ... checksum mismatch时，先别急着怀疑被人投毒。遇到过多次的情况是模块缓存里的zip是半截的，上次下载被中断，文件却留在缓存里，下次直接拿去校验。清掉重下：
go clean -modcache go mod download all go mod verify
go mod verify会重新算一遍缓存里所有模块的哈希并与go.sum比对，全通过会打印all modules verified。实测下来，网络不稳定环境里的checksum mismatch有八成是缓存问题，清缓存比查网络有效。
CI上想看清楚到底在跟谁通信，把-v和-x加上：
go mod tidy -v go build -x ./...
版本号与发布日期截至2026年9月。国内环境下的配置建议就是两条：GOPROXY写goproxy.cn加direct兜底，私有路径交给GOPRIVATE，剩下的报错再按上面的分类逐个查。