Go GOPROXY 设置为 off 后为什么新依赖下载失败

把 GOPROXY 设为 off 后，新依赖下载失败是预期行为：off 表示不允许从代理、版本控制仓库或其他来源通信。只有目标模块的版本元数据、go.mod 和源码已经完整存在于本地模块缓存，离线命令才可能继续。

解决思路不是继续换代理地址，而是先判断依赖是否已进入 GOMODCACHE。缓存完整就保持离线构建；缓存缺失则在受控联网环境预热，或把一份模块下载缓存暴露为 file:// 代理。

先确认失败的是网络来源还是本地缓存

不要一看到 module lookup disabled by GOPROXY=off 就直接修改配置。先在项目根目录查看实际生效的变量，再确认模块缓存位置和目标模块版本：

# 查看当前项目使用的代理、缓存目录和校验数据库
go env GOPROXY GOMODCACHE GOSUMDB

# 查看构建列表中的模块版本；这里只读取现有模块信息
go list -m all

# 查看指定模块在当前缓存中的下载状态
go mod download -json example.com/acme/telemetry@v1.4.2

如果最后一个命令在 GOPROXY=off 下报错，通常说明该版本的 .mod、.zip 或展开目录不完整。GOMODCACHE 只是存放位置，不是一个会自动联网补齐内容的服务。

为什么缓存里有项目依赖，新增版本仍然失败

Go 模块缓存按模块路径和版本保存内容。项目之前编译过 example.com/acme/telemetry@v1.3.0，并不代表 v1.4.2 也存在；同一个模块的不同版本不能靠路径前缀互相代替。

此外，加载一个包可能先需要读取目标版本的 go.mod，真正编译时还需要模块 zip 或展开后的源码。缺任何一层，工具链都可能尝试查找远程来源，而 off 会让这次查找直接终止。默认的 GOPROXY 是代理地址后跟 direct，但显式写成 off 后不存在这样的回退。

三种处理方式：预热、复用本地代理和回到受控代理

最稳定的做法是在允许联网的准备机上按锁定版本预热，然后把缓存随构建环境交付。不要只执行一次普通构建就认为缓存齐全，显式下载主模块的依赖更容易留痕：

# 准备机联网执行，按 go.mod 和 go.sum 补齐模块缓存
GOPROXY=https://proxy.golang.org,direct go mod download

# 在隔离机检查依赖是否都能从本地缓存读取
GOPROXY=off go mod download
GOPROXY=off go test ./...

如果构建机不能直接使用准备机的默认缓存，可以复制 $(go env GOMODCACHE)/cache/download，再指向它的文件代理：

# 指向已交付的 GOPROXY 协议目录；路径按实际挂载点替换
GOPROXY=file:///opt/go-module-proxy go mod download

# 下载完成后再切换为严格离线，验证构建不再依赖外部来源
GOPROXY=off go test ./...

需要临时恢复远程代理时，建议只在单次命令上设置变量，不要用 go env -w 把联网配置永久写入开发机。私有模块还要结合 GOPRIVATE、GONOPROXY 和凭据策略单独规划，不能把它们混同为缓存问题。

别把 go.sum、vendor 和缓存清理混成一个问题

go.sum 记录模块文件的校验和，不能代替模块源码；它存在并不意味着 zip 已经在缓存里。遇到校验和缺失时，先看依赖版本是否实际可用，再决定是否在联网环境执行 go mod download 或 go mod tidy，不要在离线机盲目删除校验文件。

vendor 也不是模块缓存的别名。使用 vendor 模式时，go build 和 go test 可以从项目内的 vendor/ 读取源码；但 go mod download、go mod tidy 仍可能访问模块缓存或网络。两种交付方式要在团队构建脚本中明确写出。

最后，go clean -modcache 会删除整份模块缓存，而且缓存通常被多个项目共享。排查前先记录 GOMODCACHE 和锁定版本，确认没有其他项目依赖它；清理后再设为 off 只会让所有缺失依赖更快暴露。

离线构建前的检查清单

• 在准备机执行 go mod download，并保存与提交版本一致的 go.mod、go.sum。
• 在隔离环境先运行 GOPROXY=off go mod download，再运行测试或构建。
• 若使用 file:// 代理，交付的是 cache/download 协议目录，而不是任意源码目录。
• 确认构建脚本没有在后台执行 go get、go mod tidy 等隐式改依赖动作。

常见问题

GOPROXY=off 能下载已经写在 go.mod 里的依赖吗？

只有对应版本的必要文件已经在本地缓存，或构建直接使用 vendor 时才可以。写在 go.mod 里只代表依赖声明存在。

把 GOPROXY 改成 direct 就一定能解决吗？

不一定。direct 只是允许直接访问版本控制仓库，仍受网络、仓库权限、私有模块配置和版本可见性影响。

为什么 go.sum 有记录，go test 还是提示下载失败？

go.sum 主要用于校验下载内容，不能提供缺失的模块源码；先确认 GOMODCACHE 中是否有目标版本的模块文件。

相关事实可在 Go Modules Reference 的环境变量说明 与 模块缓存说明中核对。把“依赖版本是否已交付”和“构建是否允许联网”拆开，GOPROXY=off 的失败就能从模糊的下载报错变成可定位的缓存边界问题。