先检查go/pkg/mod是否存在损坏的只读文件，再执行go clean -modcache彻底清空缓存，随后必须运行go mod download重新下载依赖，最后才能go build；否则会因缓存状态不一致导致静默失败或checksum mismatch。
go mod download 无法拉取依赖时先检查 go/pkg/mod 是否存在损坏的只读文件
Go 的模块缓存（$GOPATH/pkg/mod 或 $GOMODCACHE）一旦混入权限异常、损坏的 .zip 或不完整的 cache 条目，go mod download 和 go build 就会静默失败或报 invalid module cache 类错误。这不是网络问题，而是本地缓存状态不一致。
常见现象包括：go mod download -x 显示某模块解压失败、go list -m all 卡住、或者反复提示 checksum mismatch 却确认 checksum 文件未被篡改。
- 优先用
go clean -modcache—— 它会彻底清空整个模块缓存，比手动删目录更安全（自动处理锁文件和正在使用的临时状态） - 不要直接
rm -rf $GOMODCACHE：Windows 下可能因进程占用失败；Linux/macOS 下若正有go进程在读写缓存，会导致后续命令报index is out of range等低级 I/O 错误 - 执行前确认没有其他
go命令正在运行（尤其 IDE 的后台构建、VS Code 的 Go extension 自动分析）
修复后必须重新触发依赖解析，而不是直接 go build
清空缓存只是“重置状态”，不代表依赖已就位。Go 不会在 go build 时自动补全缺失模块——它只检查 go.sum 和 go.mod，发现缓存里没有对应版本，就报错退出。
正确顺序是：
- 运行
go clean -modcache - 立刻执行
go mod download（不加参数，下载go.mod中所有 indirect + direct 依赖） - 再跑
go build或go test—— 此时才真正走完整流程
如果项目用了 vendor，且 go mod vendor 后又改过 go.mod，别跳过 go mod vendor 重生成步骤，否则 vendor 目录和缓存状态会再次不一致。
一行命令？可以，但得带上下文约束
严格意义上的“一行命令”只有：go clean -modcache && go mod download。但它不是万能银弹：
- 如果
go.mod本身已损坏（比如手动编辑出错、版本号格式非法），go mod download会立即失败，报invalid version或unknown revision - 某些私有模块需要
git凭据或GOPRIVATE配置，清缓存后首次下载仍会卡在认证环节，这不是命令问题，而是环境缺失 -
go mod download默认并发拉取，若公司内网代理不稳定，可加-x查看具体哪个模块失败，再针对性重试：go mod download github.com/org/repo@v1.2.3
容易被忽略的副作用：go.sum 可能过期
go clean -modcache 不碰 go.sum，但重新下载依赖时，Go 会根据当前模块的最新校验和更新它。如果你之前手动修改过 go.sum（比如为了绕过 checksum mismatch），现在它会被覆盖。
这意味着：
- CI/CD 流水线中若校验
go.sum是否变更，这次操作大概率触发 diff - 团队协作时，建议把
go.sum更新提交，避免其他人本地复现时因校验和不匹配而构建失败 - 如果项目明确要求锁定所有间接依赖的精确哈希（例如 FIPS 合规场景），需配合
go mod tidy -compat=1.17等显式兼容性控制，不能只靠清缓存
缓存损坏本身不常发生，但一旦发生，修复动作必须连贯：清、下、验，缺一不可。中间漏掉任何一环，都可能让问题从“模块找不到”变成“校验失败”再变成“构建成功但运行时 panic”。
