先执行go clean -modcache清理缓存，再运行go mod tidy重新下载依赖；问题主因是项目重命名或module路径与导入路径不一致导致缓存映射失效。
go mod tidy 无输出但依赖没下载？先查缓存和模块路径
这不是语法错误，而是模块系统“以为自己已经完成”，实际却漏了依赖。常见于项目重命名、go.mod 中 module 声明与当前路径不一致，或缓存中残留旧版本映射。
- 运行
go list -m all，看输出里是否包含你期望的依赖；如果缺失，说明go mod tidy没识别到引用 - 检查
go.mod第一行module路径是否和项目实际导入路径一致（比如项目在github.com/myorg/app，但go.mod写的是myapp） - 执行
go clean -modcache清掉整个缓存，再跑一次go mod tidy—— 注意这会清空所有已缓存模块，首次恢复较慢
报错 “undefined: xxx” 却不是代码问题？确认是否漏编译同包文件
Go 不会自动把同目录下所有 package main 文件拉进编译，只认你显式指定的文件。所以 go run main.go 找不到 api.go 里定义的结构体，是行为正常，不是 bug。
- 要么用
go run *.go（确保当前目录只有该包的 .go 文件） - 要么明确列出：
go run main.go api.go handler.go - 更稳妥的做法是统一用
go build或go run .—— 点号表示“当前模块”，Go 会按go.mod自动解析全部依赖和同包源文件
私有仓库返回 403 或 “module lookup failed”？GOPRIVATE 配置缺一不可
设了 GOPROXY 后，所有模块默认走代理；但私有地址如 git.company.com 或 github.com/my-org/internal 不能被转发出去，否则就是 403 —— 这不是权限问题，是路由发错了地方。
- 必须加
go env -w GOPRIVATE="git.company.com,github.com/my-org/*"，通配符支持*，但不支持**或正则 - 多个域名用英文逗号分隔，中间**不能有空格**（
GOPRIVATE="a.com,b.org"✅，GOPRIVATE="a.com, b.org"❌） - 如果用 SSH 克隆，还要确保
ssh -T git@git.company.com能通；如果用 HTTPS，得提前配置 Git 凭据，或设GIT_TERMINAL_PROMPT=0避免卡在密码输入
下载中途卡住或报 zip: not a valid zip file？别硬等，直接定位损坏项
这类错误极少是网络抖动导致，大概率是某模块缓存文件损坏，或 GOSUMDB 校验失败后残留了不完整 zip。
- 加
-v参数重试：go mod download -v，看最后卡在哪一个模块 URL 上 - 找到报错中出现的模块路径（例如
github.com/some/pkg@v1.2.3），去$GOMODCACHE下对应目录删掉整个版本文件夹（路径类似$GOMODCACHE/github.com/some/pkg@v1.2.3/） - 临时关校验验证是否是根源：
go env -w GOSUMDB=off，调试完记得改回（生产环境绝不能关）
GOPROXY 常不一致。Goland 或 VSCode 可能读自己的环境变量配置，改了系统级 go env -w 后，务必在 IDE 内置终端里也执行一遍，或检查 IDE 的 Go 设置页是否覆盖了代理配置。 
