go mod download卡住时，先确认goproxy是否被子进程读取：go env -w仅写配置文件，不导出环境变量，需显式export或$env:goproxy设置，并验证日志中是否出现goproxy.cn请求；必须含,direct且配goprivate，否则私有模块失败；checksum mismatch应先清缓存go clean -modcache并检查gosumdb。
go mod download卡住时，先确认GOPROXY是否真被子进程读到
很多人的配置看似生效，但go mod download仍连proxy.golang.org，本质是环境变量没被go子进程继承。Shell里执行go env -w GOPROXY=https://goproxy.cn,direct只是写入配置文件，并不自动导出为环境变量。
- 验证方式：运行
go mod download -x github.com/gin-gonic/gin@v1.9.1，看日志里出现的是GET https://goproxy.cn/还是GET https://proxy.golang.org/ - 补救操作：在shell中显式
export GOPROXY=https://goproxy.cn,direct（Linux/macOS）或$env:GOPROXY="https://goproxy.cn,direct"（PowerShell），再试 - IDE用户必须额外在编辑器设置里配置环境变量，VS Code的Go插件不读shell的
GOPROXY
逗号分隔的GOPROXY必须含direct，否则私有模块会失败
,direct不是可选项，它是代理策略的终止符：表示对不匹配GOPRIVATE的模块走前面的代理，匹配的则跳过代理直连。漏掉它，私有Git路径（如git.example.com/internal/pkg）会被强行转发到goproxy.cn，结果404或checksum mismatch。
- 正确写法：
https://goproxy.cn,direct或https://goproxy.cn,https://private-proxy.example.com,direct - 错误写法：
https://goproxy.cn（无,direct）、https://goproxy.cn,https://proxy.golang.org（无,direct兜底） - 配套必须设
GOPRIVATE：比如go env -w GOPRIVATE=git.example.com/internal/*，否则,direct也无效
checksum mismatch别急着换源，先清缓存再验证GOSUMDB
校验失败通常不是代理问题，而是本地缓存污染或镜像源未透传官方sum记录。goproxy.cn和阿里云镜像都支持sum校验，但某些自建proxy若漏配GOINSECURE或跳过验证，就会返回错误哈希。
- 第一步：执行
go clean -modcache清空本地模块缓存 - 第二步：检查
GOSUMDB值——运行go env GOSUMDB，应为sum.golang.org或明确替换值（如sum.golang.org+replace=gosum.io） - 临时调试可用
go env -w GOSUMDB=off，但上线前务必关掉，否则失去依赖完整性保护
Docker构建中go mod download要放在COPY代码之前
在Dockerfile里，go mod download必须紧挨着COPY go.mod go.sum .之后、COPY . .之前。否则，只要代码变动，Docker缓存就会失效，每次构建都重下依赖。
- 正确顺序示例：
WORKDIR /app COPY go.mod go.sum . RUN go mod download COPY . . RUN go build -o myapp .
go mod download和go build合并成一条RUN指令——前者依赖go.mod，后者依赖全部源码，缓存粒度不同go list -m -f '{{.Path}} {{.Version}}'做轻量验证，确认模块已缓存而非实时拉取GOPROXY是否被所有go子进程读取、,direct是否启用、GOPRIVATE是否覆盖全部私有路径——这三个点任意一个漏掉，都会让整个配置退回到默认代理，白忙活。
