本质是模块缓存、代理配置与校验机制三者状态不一致，须同步修正；go mod tidy无输出说明Go认为依赖已满足，但实际import缺失，需确认模块根目录、GO111MODULE=on、清理vendor、执行go mod download && go mod verify，并检查IDE环境变量是否同步。
Go模块依赖下载卡在临时目录（如$GOPATH/pkg/mod）并报错，本质不是目录权限或磁盘满，而是模块系统在缓存路径、代理配置、校验机制三者间出现状态不一致——必须同步修正，单点操作无效。
go mod tidy 无输出但依赖没下载
这不是命令没运行，而是 Go 模块系统“认为”不需要动：它已缓存了某个版本，且当前 go.mod 中声明的版本范围与缓存匹配，但实际代码里 import 的包却找不到。
- 先确认是否真在模块根目录：执行
go list -m，若报go: not in a module，说明不在有效模块路径下 - 检查
GO111MODULE是否为on：运行go env GO111MODULE，输出必须是on，不能是auto或off - 删掉
vendor/目录（如果存在）：它会强制 Go 跳过代理和远程拉取，只读本地 vendor，导致go mod tidy不触发下载 - 手动触发一次完整同步：
go mod download && go mod verify，比tidy更激进地触达缓存底层
GOPROXY 配置生效但 still timeout
常见于 IDE 内终端或构建任务中 GOPROXY 未继承 shell 环境变量，或 direct 回退逻辑被意外屏蔽。
- 在项目根目录下直接运行
go env GOPROXY，确认输出是类似https://goproxy.cn,direct，而不是空或https://proxy.golang.org - Windows 用户注意 PowerShell 和 CMD 环境变量隔离：用
go env -w GOPROXY=...是全局写入，但某些旧版 Go（ - 如果用了
GOSUMDB=off，请确认没同时设GONOSUMDB=1—— 后者优先级更高，且不提示警告，容易漏查 - 私有域名（如
git.internal.company）必须加进GOPRIVATE：例如go env -w GOPRIVATE=git.internal.company，否则 Go 仍会尝试走代理并 404
离线环境依赖始终 “module not found”
单纯拷贝 $GOPATH/pkg/mod 目录到另一台机器，99% 失败——因为 Go 会校验 go.sum、检查 cache 元数据完整性，并尝试连接 sum.golang.org。
- 离线前必须在联网机器上跑：
go mod download && go mod verify && go clean -modcache，再打包整个$GOMODCACHE目录（不是$GOPATH/pkg/mod） - 目标机器需设：
go env -w GOPROXY=direct GOSUMDB=off，否则go build仍会发起网络请求 -
go.mod中所有依赖必须显式指定版本号（如github.com/sirupsen/logrus v1.9.0），不能用@latest或@master，这些在离线时无法解析 - 若含 replace 指向本地路径（如
replace example.com/lib => ./local-lib），确保该路径真实存在且go.mod在其子目录中，否则go list -m all会直接失败
IDE 报红 “cannot resolve directory” 但命令行正常
GoLand / VS Code 的 Go 插件默认不读取 shell 的 go env，而是用自己缓存的环境快照，尤其在重启 IDE 前改过代理，极易不同步。
- GoLand：进入
Settings → Go → GOPATH，勾选Enable Go modules integration，并在下方Go toolchain区域点击Reload project - VS Code：打开命令面板（
Ctrl+Shift+P），运行Go: Install/Update Tools，确保gopls是最新版；然后关闭所有窗口，用code --no-sandbox --disable-gpu .重新打开项目 - 验证方式：在 IDE 内置 Terminal 中运行
go env GOPROXY，输出必须和外部终端一致；若不一致，说明 IDE 启动时没加载 shell profile，需在 IDE 设置里手动填入 GOPROXY 值 - 极端情况可删 IDE 缓存：
rm -rf ~/Library/Caches/JetBrains/GoLand*/go-modules（macOS）或%LOCALAPPDATA%\JetBrains\GoLand*\go-modules（Windows）
最易被忽略的是：模块缓存（$GOMODCACHE）和 go.mod 版本声明之间存在隐式绑定关系。哪怕只改了一行 replace，Go 也会拒绝复用旧缓存中的二进制，但不会明确告诉你原因——它只会静默失败，直到你手动 go clean -modcache 并重试。
