Go模块“解压失败”实为校验或网络问题，非ZIP文件名冲突；其机制不直接解压ZIP，而是基于go.sum哈希校验后以不可变格式存缓存，并通过链接映射，故不会出现duplicate entry类错误。
Go 模块依赖解压失败跟“文件名冲突”基本无关——Go go mod download 或 go build 过程中报错的所谓“解压失败”，99% 是校验失败、网络中断、权限问题或 go.sum 不一致，不是 ZIP 文件内文件名重复导致的。
为什么不会出现 ZIP 层面的文件名冲突
Go 的模块下载机制不直接解压原始 ZIP 包到磁盘。它从 proxy（如 proxy.golang.org）或 VCS（如 GitHub）拉取模块时，会：
- 先获取
go.mod和go.sum文件 - 根据
go.sum校验每个文件的 SHA256 哈希 - 将模块内容以不可变格式存入
$GOPATH/pkg/mod/cache/download/，路径由模块路径+版本+校验和生成，天然隔离 - 构建时通过符号链接（Linux/macOS）或硬链接（Windows）映射到
$GOPATH/pkg/mod/，不涉及传统 ZIP 解包逻辑
所以你不会看到类似 “duplicate entry: foo.go” 这类 ZIP 工具报错。真遇到这类错误，大概率是手动干预了缓存目录（比如用 unzip 强行解压、误删部分文件、或挂载卷权限异常）。
实际导致 “解压失败” 类错误的常见原因
终端里看到类似 failed to extract ...: invalid checksum、cannot decompress ...: unexpected EOF 或 read tcp ...: i/o timeout，本质是：
立即学习“go语言免费学习笔记（深入）”；
-
go.sum记录的哈希与实际下载内容不匹配（上游改包、代理篡改、本地缓存损坏） - 代理或私有仓库返回了不完整响应（尤其大模块 + 网络不稳定）
-
GOSUMDB=off但未配GONOSUMDB，导致校验跳过却仍尝试验证 - 磁盘满、
/tmp权限不足、SELinux/AppArmor 限制临时解压行为
执行 go mod download -v github.com/some/pkg@v1.2.3 可看到详细日志，重点关注最后一行是否含 checksum mismatch 或 unexpected EOF。
修复步骤：从缓存清理到校验重置
别碰 ZIP 文件，按顺序做这几件事：
- 运行
go clean -modcache彻底清空模块缓存（这是最安全的第一步） - 确认
go env GOSUMDB是sum.golang.org；若设为off，临时恢复：go env -w GOSUMDB=sum.golang.org - 检查代理配置：
go env GOPROXY应为有效地址（如https://proxy.golang.org,direct），私有域名需加进GONOPROXY - 重新触发下载：
go mod download github.com/some/pkg@v1.2.3；若仍失败，加-x查看 curl 日志定位网络环节 - 最后才考虑手动编辑
go.sum：仅当确认上游已修正且你信任该变更时，删掉对应行再go mod download自动重写
所有操作都不需要、也不应该去解压或修改 pkg/mod/cache/download/ 下的任何 ZIP 文件。
真正要警惕的是缓存目录被外部工具（比如 IDE 的自动清理、CI 脚本里的 rm -rf *）误删部分内容，或者 go.sum 被 Git 合并冲突残留了半截哈希——这些比“文件名冲突”现实得多，也更容易漏查。
