Go 依赖下载被代理或校验服务阻断怎么办

Go 依赖下载失败时，先从错误中的请求主机判断卡在模块获取还是校验查询，再修复对应的、经过组织批准的访问路径。GOPROXY 负责模块来源，GOSUMDB 负责公开模块的校验数据库；两者不是同一个开关。完全离线的构建则需要提前准备依赖内容和工具链，不能只复制 go.sum，也不建议用关闭校验掩盖网络或来源问题。

我在比较这几种配置时，最看重的是“故障恢复后，还能否解释依赖从哪里来”。下面用一个单模块项目迁入受限构建机的假设场景展开，不冒充亲历事故，也不提供实测日志。本文命令是给读者在自己的授权环境中使用的示例，制作文章时未实际执行。

Go 官方模块参考：https://go.dev/ref/mod；工具链说明：https://go.dev/doc/toolchain。

先看依赖从哪里来，而不是连续更换地址

设想开发机可以构建，而新构建机在依赖下载时超时。我会先保存失败命令、模块路径和版本、错误主机以及 HTTP 状态，再看有效配置。这样至少能区分“代理没有返回模块”和“模块已获取，但校验查询无法完成”。终端里同一个 timeout 单词并不能给出根因。

# 查看当前进程实际使用的配置；不要把包含凭据的结果贴到公开日志。
go env GOPROXY GOSUMDB GOPRIVATE GONOPROXY GONOSUMDB GOMODCACHE
# 检查工具链是否可能独立触发下载。
go env GOTOOLCHAIN GOWORK

这些输出可能受操作系统环境变量、持久化 go env 配置和 CI 作业设置共同影响。我更倾向先用单次命令环境变量表达试验范围，而不是立即 go env -w 修改机器默认值。涉及企业代理、证书或认证时，应按组织提供的配置处理，不把 403 当作可以自行绕开的限制。

模块拿到了，为什么校验服务还会报错

go.sum 记录的是依赖内容的已知哈希，不是依赖源码。Go 下载模块内容时，会将其与已有记录比较；缺少相应记录时，公开模块可能需要查询校验数据库。因此一个代理地址能访问，不意味着所有必要的校验查询也能完成。

GOSUMDB 配置包含数据库身份，必要时还包括公钥和服务地址。这里我不推荐把一个不明镜像地址随意塞进去：可连通不等于可信。应采用官方文档或组织维护者确认的数据库配置；代理支持校验数据库镜像时，相关查询也可能经代理提供，不一定直接访问数据库主机。

GOSUMDB=off 会停止使用校验数据库，并不替你恢复网络，也不代表下载内容因此可靠；已有 go.sum 的匹配检查与数据库查询也不能混为一谈。私有模块应按真实私有路径配置 GOPRIVATE 或相应的细粒度设置，不应把全部公共模块都标成私有来消除报错。若公共依赖出现 checksum mismatch，我会停止使用该次取得的内容并调查来源与历史记录，不删除 go.sum 让错误“消失”。

离线材料里，缓存、校验记录和 vendor 各存什么

我的取舍是：只交付一个固定项目时，vendor 的交付边界比较直观；多个项目共享依赖时，受控模块代理或准备完备的缓存更便于集中管理，但维护范围也更大。两者都不是“复制一个文件即可永远离线”。特别是缓存里已有某个模块，不代表当前版本的元数据、源码和校验材料一定齐全。

逗号后面的 direct 为什么没有救场

GOPROXY 列表的分隔符会影响回退。逗号只在前一来源返回 404 或 410 时继续尝试；超时、403 或其他错误通常会停止这条回退链。竖线表示遇到任意错误时继续尝试下一来源。这个差别解释了“配置了 direct 仍然超时”的一种原因，但不是更改企业策略的许可。

direct 代表直接访问源码仓库，并不是离线模式；它仍需要网络、仓库权限和相应版本控制工具。若企业代理承担依赖准入控制，擅自把逗号换成竖线可能跳过它的拒绝结果。我会先确认该错误是服务故障还是准入拒绝，然后按批准的恢复路径处理；没有允许访问的备用来源，就不配置自动回退。

排查后的结果判断应很具体：原先的代理请求是否恢复，原先的校验查询是否恢复，失败模块的指定版本是否可被正常获取。只看“换设置后另一个命令成功”，可能只是命中了本地缓存，不能证明原有访问路径恢复。

给固定单模块项目准备一份可用的离线交付

以下方案假定当前目录是单模块根目录，不使用工作区模式；联网准备机有经过批准的模块来源，且工具链版本与目标环境匹配。go mod vendor 会重建 vendor，原有手工修改可能丢失，因此先保存确有价值的本地改动，不要把修改直接留在依赖副本里。

# 在获准联网的准备机执行；失败时停止交付，不携带半成品。
GOWORK=off go mod download
GOWORK=off go mod vendor
# 把源码、go.mod、go.sum、vendor（含 modules.txt）一起纳入交付。

不要在受限机上再运行 go mod tidy 或 go mod download，指望它们自动遵守 vendor 的离线边界；这些模块管理命令仍可能访问网络。下面只对构建指定使用 vendor，同时禁用自动工具链下载；前提是机器已经安装满足项目要求的 Go 版本。

# 在已准备完整材料的单模块根目录执行。
# GOPROXY=off 禁止模块获取回退；local 要求使用本地工具链。
GOWORK=off GOPROXY=off GOTOOLCHAIN=local go build -mod=vendor ./...
# 如需测试，仍须确认测试代码本身不会调用外部服务。
GOWORK=off GOPROXY=off GOTOOLCHAIN=local go test -mod=vendor ./...

命令成功退出是该环境下构建或测试完成的判断，不意味着所有后续任务都能离线。CGO 依赖、系统头文件、独立生成工具和测试访问的业务服务仍需要分别准备；GOPROXY=off 也不是禁止进程所有网络访问的沙箱。若 Go 报 inconsistent vendoring，应回到准备机用匹配的 go.mod 重建材料，而不是在离线机临时修补清单。

恢复以后，我会保留什么而不急着清空缓存

网络出问题时直接清空模块缓存，会把原本可用的依赖也移走，离线条件下尤其难以恢复。我会先保留配置变更前后的差异、失败主机和模块版本，再处理明确损坏的材料；不把全局清理当成第一步。交付侧应保存源码版本、Go 版本与依赖清单，让下一次复现仍有明确基线。

若只是一次性试用环境变量，上述命令结束后不会把这些单次设置写入 go env 的持久配置。若此前已经修改机器默认值，则应根据变更记录恢复原值，而不是猜测一个所有机器通用的默认配置。

换了 GOPROXY，为什么仍访问校验服务？

因为模块来源与内容认证是不同职责。先确认错误发生在哪一项请求，再采用批准的数据库访问或代理镜像配置，不用关闭校验替代排障。

只有 go.sum 能在离线机重新构建吗？

不能。它只有哈希记录，仍需要依赖源码、合适的 Go 工具链和可能的系统构建依赖。

有 vendor 后还需要 go mod download 吗？

按上述交付方案，目标机直接用 -mod=vendor 构建；不要把依赖管理命令混进离线构建步骤。新增依赖应回到联网准备环境更新交付。

对我来说，最稳妥的修复不是让错误提示少一行，而是把来源、认证和交付材料分别解释清楚。允许联网的项目修复受控访问路径；固定离线项目准备完整材料。两种环境各自有清晰边界，才不需要依靠关闭校验来维持构建。