解决Golang模块依赖下载时因为本地磁盘空间不足导致的下载截断-Golang-PHP中文网

go mod download失败实际是磁盘写入失败：剩余空间不足导致tar包截断、zip解压损坏或checksum验证卡住，表现为checksum mismatch或unexpected eof；应检查df -h确认$gocache和$gopath/pkg/mod空间，执行go clean -cache -modcache清理，或重定向gomodcache/gocache至大容量分区。

解决golang模块依赖下载时因为本地磁盘空间不足导致的下载截断

Go mod download 失败但无明确错误提示，实际是磁盘写入失败

Go 工具链在执行 go mod download 时，如果目标目录（通常是 $GOCACHE 或 $GOPATH/pkg/mod）所在磁盘剩余空间不足，不会报 “disk full” 类错误，而是静默截断 tar 包、损坏 zip 解压、或卡在某个模块的 checksum 验证阶段——最终表现为 verifying github.com/some/pkg@v1.2.3: checksum mismatch 或 unexpected EOF。

这不是网络或代理问题，也不是模块本身损坏，而是本地磁盘写入中途失败后残留了不完整文件，后续验证必然失败。

检查磁盘空间：运行 df -h $GOCACHE（默认为 $HOME/Library/Caches/go-build macOS / $HOME/.cache/go-build Linux）和 df -h $GOPATH/pkg/mod（默认为 $HOME/go/pkg/mod）
确认是否真满：注意某些系统（如 macOS APFS）会显示“可用空间”但实际因快照/Time Machine 占用导致无法写入
临时清理缓存：可安全执行 go clean -cache -modcache，它会清空 $GOCACHE 和 $GOPATH/pkg/mod，但不会影响你自己的源码

把 Go 模块缓存移到空间充足的磁盘分区

硬清缓存只是治标；若项目依赖多（尤其含大量二进制 asset 或大体积 testdata 的模块），反复下载仍会填满原分区。更可靠的做法是重定向 $GOMODCACHE 和 $GOCACHE 到另一块盘。

注意：$GOMODCACHE（模块下载与解压位置）和 $GOCACHE（构建对象缓存）是两个独立路径，必须分别设置，且需在执行 go mod download 前生效。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。

下载

Linux/macOS：在 shell 配置中添加两行（例如 ~/.zshrc）：

export GOMODCACHE="/mnt/bigdisk/go-mod-cache"
export GOCACHE="/mnt/bigdisk/go-build-cache"

Windows（PowerShell）：

$env:GOMODCACHE="D:\go-mod-cache"
$env:GOCACHE="D:\go-build-cache"

验证是否生效：go env GOMODCACHE GOCACHE，输出应为你指定的新路径
首次使用新路径时，go mod download 会重新拉取全部模块，但后续增量更新不再受原磁盘限制

避免 go get / go mod tidy 触发隐式下载导致磁盘再次爆满

go get 和 go mod tidy 默认会自动下载缺失模块并写入 go.sum，如果此时 $GOMODCACHE 仍指向旧路径，或环境变量未被子 shell 继承（比如 IDE 内置终端未加载配置），就会回退到默认位置，再次触发磁盘写满。

检查当前终端是否真正继承了新变量：echo $GOMODCACHE，不是看 go env 输出——后者可能缓存旧值
VS Code 用户：确保 "terminal.integrated.env.linux"（或对应平台）配置了 GOMODCACHE 和 GOCACHE，否则集成终端会走默认路径
CI/CD 场景：在脚本开头显式 export，不要依赖用户 profile；例如 GitHub Actions 中：
```
env:
  GOMODCACHE: /tmp/go-mod-cache
  GOCACHE: /tmp/go-build-cache
```
临时应急：可在命令前加前缀强制覆盖，如 GOMODCACHE=/big/go-mod go mod download

模块下载中断后残留损坏文件的清理策略

即使腾出了空间，go mod download 仍可能失败——因为上次中断时已在 $GOMODCACHE 下写入了不完整 .zip 或损坏的 cache/download/ 条目，Go 不会自动跳过校验。

手动清理比等工具自动修复更可靠，尤其是当你看到 checksum mismatch 且确认网络和模块本身无误时。

定位损坏模块：错误信息里的路径通常形如 github.com/some/pkg@v1.2.3，对应缓存路径为 $GOMODCACHE/github.com/some/pkg/@v/v1.2.3.zip 及其同名 .info、.mod 文件
一键清理整个模块版本：rm -f $GOMODCACHE/github.com/some/pkg/@v/v1.2.3.*
彻底重置所有模块缓存（谨慎）：rm -rf $GOMODCACHE/*，再跑 go mod download ——这比 go clean -modcache 更彻底，后者有时漏删部分索引文件
验证清理效果：运行 go list -m all | head -5 看是否能正常解析，而非卡住或报错