报错“no required module provides package”本质是Go无法将import路径映射到已知模块，需依次检查：①当前目录是否存在go.mod（无则go mod init example.com/myapp）；②import路径拼写是否正确；③是否误入$GOPATH/src导致退化为GOPATH模式；④是否执行go get模块根路径（如github.com/cloudwego/hertz@latest）而非子包；⑤GOPROXY是否配置为https://goproxy.cn,direct且GOSUMDB未被墙阻塞校验。
go mod tidy 报 “no required module provides package” 怎么办
这不是缺包，而是 Go 没法把 import 路径映射到已知模块。常见于刚建项目、路径拼错、或没执行初始化。
- 先确认当前目录下有
go.mod：没有就运行go mod init example.com/myapp（模块名可任意，但需是合法域名格式） - 检查 import 路径是否拼错，比如
github.com/cloudwego/hertz/pkg/app/server少了个/server就会触发该报错 - 确保没误入
$GOPATH/src目录——只要路径在里面，哪怕GO111MODULE=on也会退化为 GOPATH 模式，拒绝模块解析 - 运行
go get github.com/cloudwego/hertz@latest（而非子路径），让 Go 自动推导模块根路径并写入go.mod
GOPROXY 配错了导致 timeout 或 403
国内环境默认代理 https://proxy.golang.org 基本不可达，不改就卡在 DNS 或 TLS 阶段，不是网速问题，是根本连不上。
- 设成带 fallback 的组合：
go env -w GOPROXY=https://goproxy.cn,direct（direct必须保留，否则私有库拉不到） - 验证是否生效：
go env GOPROXY输出应为https://goproxy.cn,direct，不是空或原始值 - Windows PowerShell 用户别用
$env:GOPROXY=...临时设置——IDE 和 CI 不认，必须用go env -w - 如果公司用 GitLab 私有库，还要加
go env -w GOPRIVATE=git.example.com,github.com/my-org/*（逗号分隔，无空格，支持通配）
离线或局域网里 go mod download 失败
命令卡住或报 dial tcp: i/o timeout，本质是 Go 还在试图连 proxy.golang.org 和 sum.golang.org，两个都得关掉。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 必须同时执行：
go env -w GOPROXY=off和go env -w GOSUMDB=off - 离线缓存不能“边下边拷”：得先在有网机器上跑完
go mod download，再完整拷贝$(go env GOMODCACHE)目录到离线机相同路径 - 检查离线机
go version是否和下载机一致——不同 Go 版本的缓存结构可能不兼容 - 若用了
replace指向本地路径，确保路径存在且go.mod中写法与实际文件系统一致（Windows 注意反斜杠/斜杠）
checksum mismatch 或 verifying 卡住不动
真正卡住的往往不是下载，而是校验阶段。sum.golang.org 被墙后 Go 会反复重试，直到超时。
立即学习“go语言免费学习笔记（深入）”；
- 临时跳过校验：
go env -w GOSUMDB=off（仅限可信离线环境） - 国内可用替代：
go env -w GOSUMDB=sum.golang.google.cn（比off更安全） - 如果
go.sum已损坏，删掉它再跑go mod download，Go 会重新生成 - 注意：
go mod verify在GOSUMDB=off下直接返回 success，不校验——这点容易被忽略，以为“没问题”，实则跳过了完整性检查
