go mod download在子目录不工作，因go只认go.mod所在目录为模块根；需用go list -m验证位置，find . -name go.mod定位后cd进入再执行，否则静默失败。
go mod download 在子目录里不工作？先确认是否在 module 根目录
Go 模块系统只认 go.mod 所在目录为 module 根，不在该目录下执行 go mod download 或 go mod tidy，命令会静默失败或报 no required module provides package —— 这不是网络问题，是路径错了。
常见现象：项目结构是 project/backend/api/，你在 api/ 目录下运行 go mod tidy，没报错也没下载依赖。
- 用
go list -m检查当前是否在 module 内：有输出（如example.com/project）说明位置对；无输出或报错，说明不在根目录 -
find . -name go.mod找到最近的go.mod，cd 进去再操作 - VSCode 中右下角状态栏显示的 module 路径必须和当前终端 pwd 一致，否则
gopls会误判为 GOPATH 模式
GOPROXY 配置生效但子模块仍卡住？检查 GOPRIVATE 和 GONOPROXY 是否覆盖完整
多级嵌套项目常含私有子模块（如 project/internal/auth、project/libs/logging），一旦这些路径没被 GOPRIVATE 或 GONOPROXY 覆盖，Go 就会把请求发给代理，结果 403 或 timeout。
注意：GOPRIVATE 控制「跳过校验 + 跳过代理」，GONOPROXY 只控制「跳过代理」，两者语义不同。
- 若子模块走 HTTPS 私有 Git（如
https://git.corp.com/project/internal/auth），设go env -w GOPRIVATE="git.corp.com" - 若子模块路径是
example.com/project/internal/*，则GOPRIVATE必须包含example.com/project/internal/*，通配符只匹配路径前缀，不支持** - 多个域名/路径用英文逗号分隔，不能有空格，例如
git.corp.com,github.com/my-org/* - 验证配置：执行
go env GOPRIVATE和go env GONOPROXY，确保输出是你期望的值
go mod tidy 无输出却没下载依赖？大概率是缓存污染或 go.sum 锁定旧版本
嵌套项目中，不同子目录可能曾独立 init 过 module，导致 $GOPATH/pkg/mod 缓存里混入了冲突路径或损坏 zip 包，go mod tidy 会跳过已“认为存在”的依赖，哪怕它们根本不可用。
典型表现：执行 go mod download -v 显示某包 “already downloaded”，但编译时提示 cannot find package。
- 先清理缓存：
go clean -modcache（注意：这会清掉所有模块，后续首次下载稍慢） - 再强制重新解析：
go mod graph | head -20看依赖树是否正常展开；若中断，说明某个间接依赖路径解析失败 - 若报
checksum mismatch，临时关校验：go env -w GOSUMDB=off（仅调试，勿提交） - 删掉项目根目录下的
go.sum，再跑go mod tidy让它重生成（前提是go.mod版本声明准确）
子模块用 replace 指向本地路径，但 go mod download 不生效？replace 不触发下载
replace 是重写导入路径的指令，它让 Go 编译时从指定位置（如 ./internal/auth）读代码，但 go mod download 默认只处理远程依赖 —— 本地路径不会被下载，也不会出现在 go.mod 的 require 列表里。
这本身不是 bug，而是设计行为。但容易让人误以为“依赖没拉下来”。
- 若子模块是本地开发中的，确保该路径存在且含有效
go.mod；go build能通过即说明 replace 生效 - 若想把本地子模块也纳入统一版本管理（比如发布到私有 registry），需先
git tag并推送到远端，再把replace改成require example.com/project/internal/auth v0.1.0 - 避免在
replace后还手动go get该路径 —— 会破坏 replace 的指向，导致 import 冲突
go.mod、replace 和 require 混用、缓存残留旧路径。动手前先 go list -m all 看实际加载的模块列表，比盲目调代理更省时间。
