GOMODCACHE 权限错误的目录与环境变量排查

遇到 permission denied、module cache 或下载依赖失败时，先别急着给整个项目目录加写权限。Go 真正写入的是模块缓存，路径由 GOMODCACHE 决定；它没有设置时通常回落到 GOPATH/pkg/mod。先把实际路径查出来，再检查父目录和缓存子目录，通常比反复执行 go get 更快定位。

官方文档：https://go.dev/ref/mod

先确认 Go 到底在写哪个缓存目录

先读取 Go 的有效配置，而不是只看 shell 里有没有写过 GOMODCACHE。下面的命令只做观察，输出中的路径就是后续权限检查的目标。

# 读取模块缓存、GOPATH、构建缓存和持久化环境文件的位置
go env GOMODCACHE GOPATH GOCACHE GOENV

# 查看当前项目会采用的模块模式和下载代理
go env GO111MODULE GOPROXY

如果 GOMODCACHE 已明确指向某个目录，就不要再按默认路径排查。若它为空或没有单独配置，再结合 GOPATH 推导 GOPATH/pkg/mod。GOCACHE 存的是编译产物，修复它不能解决模块目录无法写入的问题。

用权限证据定位真正的阻塞点

拿到路径后，沿着路径从上到下检查。Unix 系统中，当前用户需要对每一级父目录拥有进入权限，对最终缓存目录拥有创建或修改权限；只看最后一级的权限位容易漏掉父目录限制。

# 替换为上一步实际输出的路径；先看每一级目录的属主和权限
namei -l "$GOMODCACHE"

# 查看模块缓存与下载子目录的状态，不修改任何文件
ls -ld "$GOMODCACHE" "$GOMODCACHE/cache" "$GOMODCACHE/cache/download" 2>/dev/null

# 用当前用户做一次最小写入测试，完成后立即删除测试文件
touch "$GOMODCACHE/.write-check" && rm "$GOMODCACHE/.write-check"

namei 不存在时，可以逐级使用 ls -ld。如果路径由旧用户创建，常见现象是当前用户能读取已有依赖，却不能新增版本；如果父目录没有执行权限，则即使末级目录显示可写也会失败。容器或 CI 还要核对挂载卷的属主、运行 UID，以及是否以只读方式挂载。

迁移或修复后，再验证配置不会被写回来

个人环境中，迁移到当前用户拥有的路径通常更稳。先创建目标目录，再用 go env -w 持久化；不要把 sudo go get 当作长期方案，因为它可能继续生成由 root 拥有的缓存内容。

如果必须保留原路径，应由管理员修复属主、组和目录权限，并确认挂载策略允许写入。改完后再次执行 go env GOMODCACHE、最小写入测试和 go mod download。缓存内容是 Go 管理的只读模块文件，不建议手工修改其中的源码；需要清理时使用 go clean -modcache，而不是直接对缓存做递归删除。

常见问题

GOMODCACHE 和 GOCACHE 是同一个目录吗？

不是。前者保存下载的模块文件，后者保存编译缓存。报错中出现 module cache 时，应先看 GOMODCACHE。

直接删除 GOPATH/pkg/mod 能解决权限错误吗？

不一定。删除只能清掉旧内容，不能修复父目录不可进入、挂载只读或下一次又被写回的环境配置。优先确认路径和用户。

为什么不用 sudo 执行 go mod download？

提权可能让缓存混入另一个用户的属主，导致普通用户后续仍然无法写入。更可靠的做法是让运行 Go 的用户拥有明确、持久的缓存路径。