命令 go get 卡住、超时或返回 dial tcp: i/o timeout — 这是在公司防火墙、封闭网络或使用私有 GitLab/GitHub 仓库的开发人员常见的情况。在 90% 的情况下,原因在于 GOPROXY 配置错误、缺少 GOPRIVATE 或防火墙阻止直接访问 proxy.golang.org。我们将讨论如何正确修复这个问题。
为什么 Go 模块无法下载
从 Go 1.13 版本开始,模块系统默认访问公共代理 proxy.golang.org 和校验和服务器 sum.golang.org。如果这两个服务在网络层面被阻止(这在俄罗斯、中国和有限制的企业网络中很常见),命令 go build 或 go mod tidy 将会挂起直到超时,然后返回错误:
go: github.com/some/[email protected]: reading github.com/some/package/@v/v1.2.3.info: dial tcp 142.250.x.x:443: i/o timeout
有三种典型场景会导致模块下载失败:
- 网络阻塞 — 提供商或企业防火墙切断对 Google 基础设施的访问,而 proxy.golang.org 和 sum.golang.org 就托管在此基础设施上。
- 私有仓库 — 模块位于内部 GitLab/Bitbucket 中,公共 GOPROXY 无法访问,同时还试图在 sum.golang.org 上验证其校验和,尽管不应该这样。
- 网络中的代理服务器未配置环境变量 — 外部流量仅通过 HTTP/SOCKS5 代理发送,但 Go 并不知道,因为
go get使用的是标准的 net/http 客户端,它读取的是环境变量,而不是浏览器的系统代理设置。
接下来我们将逐一讨论每种情况,并提供具体的命令和配置文件。
什么是 GOPROXY 及其工作原理
GOPROXY 是一个环境变量,指示 Go 工具从哪里下载模块。默认情况下(从 Go 1.14 开始),其值为:
GOPROXY=https://proxy.golang.org,direct
逗号分隔的值是 Go 按顺序遍历的源列表。direct 表示“如果代理返回 404 或 410,则直接从 VCS(git、svn、hg)下载”。如果代理物理上不可用(超时,而不是 404),Go 不会转到下一个源 — 它会挂起或因超时而失败。这是许多人不理解的关键点:回退机制仅在“未找到模块”时有效,而不是在“网络不可用”时。
除了 proxy.golang.org,还有可以用作替代的公共镜像:
| GOPROXY 服务器 | URL | 特点 |
|---|---|---|
| Google 官方 | proxy.golang.org | 在封闭网络中经常被阻止 |
| goproxy.cn | goproxy.cn | 来自中国社区的镜像,稳定可用 |
| Astra (goproxy.io) | goproxy.io | 替代的全球镜像 |
| Athens (自托管) | 自己的服务器 | 完全控制,适合企业模块缓存 |
GOPROXY 配置:有效的配置
Go 的环境变量可以临时设置(会话)或通过 go env -w 永久设置,这会将值保存到 Go 配置文件中(通常在 Linux/macOS 上为 ~/.config/go/env,在 Windows 上为 %APPDATA%\go\env)。
永久配置(推荐):
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
检查当前值:
go env GOPROXY
如果需要多个镜像作为备份:
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
重要提示:如果列表中的第一个代理响应超时,而不是 HTTP 错误,转到下一个源可能需要每个模块最多一分钟 — 这会降低 CI 中的构建速度。因此,如果网络物理上无法访问第一个代理,最好立即将其从列表中删除或通过代理服务器配置网络访问(见下文),而不是依赖回退。
如果希望完全禁用对外部代理的访问,仅从本地缓存或直接从 VCS 工作:
go env -w GOPROXY=direct
GOPRIVATE、GONOSUMCHECK 和 GOSUMDB
当模块位于内部 Git 仓库(企业 GitLab、Bitbucket Server、自托管 Gitea)时,Go 默认仍然会尝试通过公共 GOPROXY 进行检查,并通过 GOSUMDB 校验哈希 — 这是不可能的,因为私有代码不会公开。结果是错误 410 Gone 或 verifying module: checksum mismatch。
解决方案是设置 GOPRIVATE 变量,告诉 Go:“这些模块路径是私有的,不要去公共代理查找,也不要验证校验和”。
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE 会自动设置两个标志:GONOSUMCHECK(禁用通过 GOSUMDB 的哈希检查)和 GOPROXY=direct 针对指定路径。但如果需要更细致的配置,可以单独设置它们:
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
对于 GitHub 上的私有仓库,还需要配置 git 使用令牌而不是 SSH 通过 HTTPS 克隆,因为 Go 工具在底层使用 git:
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
此命令将所有对 github.com 的 HTTPS 请求替换为带令牌的 URL 请求,使 Go 客户端能够在不交互输入用户名/密码的情况下下载私有模块。
用于 go get 的 HTTP/HTTPS 代理
如果办公室或服务器位于企业 HTTP 代理后面(例如,Squid),Go 不会自动识别这一点 — 它只读取环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY,这些是 Go net/http 客户端的标准。
Linux / macOS (bash/zsh):
export HTTP_PROXY=http://user:password@proxy-host:3128 export HTTPS_PROXY=http://user:password@proxy-host:3128 export NO_PROXY=localhost,127.0.0.1,gitlab.company.com
为了避免每次都手动输入,请将这些行添加到 ~/.bashrc、~/.zshrc 或 ~/.profile 中。
Windows (PowerShell):
$env:HTTP_PROXY = "http://user:password@proxy-host:3128" $env:HTTPS_PROXY = "http://user:password@proxy-host:3128" $env:NO_PROXY = "localhost,127.0.0.1"
要在 Windows 上永久保存,请使用 setx:
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
重要提示:NO_PROXY 应包括内部域(内部 GitLab、本地 Athens 服务器),否则对它们的请求也会通过外部代理发送,并会因访问错误而失败。
如果公共 GOPROXY 无法访问不是由于内部防火墙,而是由于特定区域的地理封锁 — 这是服务器分布在不同国家的团队面临的情况 — 可以通过外部代理服务器建立出站隧道以获取所需的地理位置。对于这种场景,数据中心代理 是合适的选择 — 它们提供稳定快速的通道和可预测的延迟,这在 CI 流水线中批量下载依赖时至关重要。
SOCKS5 代理和绕过封锁
HTTP_PROXY/HTTPS_PROXY 变量不仅支持 HTTP(S) 代理,还支持 SOCKS5 — 从 Go 1.10+ 开始,标准库能够通过 socks5:// 协议工作:
export ALL_PROXY=socks5://user:password@proxy-host:1080 export HTTP_PROXY=socks5://user:password@proxy-host:1080 export HTTPS_PROXY=socks5://user:password@proxy-host:1080
变量 ALL_PROXY 是通用的,许多 CLI 工具(不仅仅是 Go)都会读取它。如果您已经有一个 SOCKS5 隧道(例如,通过 SSH:ssh -D 1080 user@remote-host),可以通过它发送所有 go get 流量,而无需在服务器上进行额外配置。
为了测试来自不同地区的构建(例如,检查 CI 流水线在请求区域镜像包时的表现,或外部服务对来自特定国家请求的反应),通常需要一个真实 IP 地址的通道,类似于普通用户,而不是数据中心。在这种情况下,可以选择 住宅代理 — 它们更少受到模块分发服务器或私有包注册表的自动限制。
可以通过简单的命令和详细输出检查 Go 是否实际使用代理:
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
标志 -x 打印每个执行的命令,包括网络请求,这有助于了解 go get 是否通过代理进行,或者忽略了环境变量(如果变量在另一个终端会话中导出或未传递给子进程,则会发生这种情况)。
CI/CD 和 Docker 中的代理
在 CI 运行器(GitHub Actions、GitLab CI、Jenkins)中,需要通过作业设置显式传递环境变量,而不是依赖于本地的 .bashrc,因为在容器中无法读取。
GitLab CI (.gitlab-ci.yml):
variables:
GOPROXY: "https://goproxy.cn,direct"
GOPRIVATE: "gitlab.company.com/*"
HTTPS_PROXY: "http://user:password@proxy-host:3128"
build:
script:
- go mod download
- go build ./...
Dockerfile(多阶段构建):
FROM golang:1.22 AS builder
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV GOPROXY=https://goproxy.cn,direct
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o app .
构建参数在调用 docker build 时传递:
docker build --build-arg HTTP_PROXY=http://user:password@proxy-host:3128 \ --build-arg HTTPS_PROXY=http://user:password@proxy-host:3128 \ -t myapp .
如果构建在多个运行器上并行进行,并且需要避免因大量并发请求而导致的模块镜像 IP 被封禁(在高负载下的自托管 Athens 代理中可能发生),通过轮换 IP 来分散出站请求是有用的。为了均匀分配负载并避免代理服务器的速率限制,通常使用数据中心代理 — 它们提供低延迟,这对 CI 至关重要,因为每一秒的延迟都会乘以作业的数量。
常见错误及其解决方案
| 错误 | 原因 | 解决方案 |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org 在网络中不可用 | 将 GOPROXY 更改为镜像或配置 HTTP_PROXY |
410 Gone |
私有模块对公共代理不可用 | 为所需模块路径配置 GOPRIVATE |
checksum mismatch |
GOSUMDB 尝试检查私有模块 | 通过 GONOSUMDB 或 GOSUMDB=off 禁用检查 |
x509: certificate signed by unknown authority |
企业代理替换 TLS 证书(MITM) | 将公司根证书添加到系统存储中 |
repository not found |
没有访问私有 git 仓库的令牌 | 使用令牌配置 git config url.insteadOf |
| 代理变量被忽略 | 导出在其他 shell/session 中进行 | 在运行 go 的同一会话中通过 env | grep PROXY 检查 |
特别需要提到 MITM 代理(企业 Squid/Zscaler 通过替换证书):如果这样的代理拦截 HTTPS 流量进行分析,Go 客户端将不信任其自签名证书,这会导致 x509 错误。解决方案是导出公司根证书为 PEM 格式,并将其指定为变量:
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
此变量在 Go 运行时检查 TLS 链时读取,允许通过企业 MITM 代理工作,而不必完全禁用证书检查(出于安全考虑,不应这样做)。
结论
如果 Go 模块无法下载,90% 的情况下只需三个步骤:设置有效的 GOPROXY(公共镜像替代被阻止的 proxy.golang.org)、为内部仓库添加 GOPRIVATE,并在网络仅通过企业代理访问外部时配置 HTTP_PROXY/HTTPS_PROXY。对于 CI/CD,这些变量需要通过作业的环境变量或 Docker 的构建参数显式传递,而不是依赖于开发者的本地配置。
如果故障原因是模块镜像的地理封锁或在 CI 中并行构建时代理服务器的速率限制,建议通过稳定的外部通道发送出站流量。对于这种任务,数据中心代理 是很好的选择 — 低延迟和可预测的带宽在批量下载依赖时至关重要。如果需要在测试外部服务的可用性时模拟普通用户流量,可以选择 住宅代理 — 它们更少引起模块分发服务器的安全系统的怀疑。