Der Befehl go get hängt, schlägt mit einem Timeout fehl oder gibt dial tcp: i/o timeout aus — eine vertraute Situation für Entwickler hinter einer Unternehmensfirewall, in einem geschlossenen Netzwerk oder bei der Arbeit mit privaten GitLab/GitHub-Repositories. In 90% der Fälle liegt das Problem an einer falschen Konfiguration von GOPROXY, dem Fehlen von GOPRIVATE oder der Blockierung des direkten Zugriffs auf proxy.golang.org durch eine Firewall. Lassen Sie uns besprechen, wie man das richtig behebt.
Warum Go-Module nicht heruntergeladen werden
Seit Go 1.13 greift das Modulsystem standardmäßig auf den öffentlichen Proxy proxy.golang.org und den Prüfdienst sum.golang.org zu. Wenn beide Dienste auf Netzwerkebene blockiert sind (was typisch für Russland, China und Unternehmenssegmente mit Einschränkungen ist), wird der Befehl go build oder go mod tidy bis zum Timeout hängen bleiben und dann einen Fehler ausgeben:
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
Es gibt drei typische Szenarien, die das Herunterladen von Modulen verhindern:
- Netzwerkblockade — der Anbieter oder die Unternehmensfirewall schneidet den Zugang zur Google-Infrastruktur ab, auf der proxy.golang.org und sum.golang.org gehostet werden.
- Private Repositories — das Modul befindet sich in einem internen GitLab/Bitbucket, und der öffentliche GOPROXY kann physisch nicht darauf zugreifen, während er gleichzeitig versucht, die Prüfziffer auf sum.golang.org zu überprüfen, obwohl er das nicht sollte.
- Proxy-Server im Netzwerk ohne konfigurierte Umgebungsvariablen — der Datenverkehr nach außen erfolgt nur über HTTP/SOCKS5-Proxys, aber Go weiß nichts davon, weil
go getden Standard net/http-Client verwendet, der Umgebungsvariablen liest und nicht die Proxy-Systemeinstellungen aus dem Browser.
Lassen Sie uns jeden Fall mit spezifischen Befehlen und Konfigurationsdateien näher betrachten.
Was ist GOPROXY und wie funktioniert es
GOPROXY ist eine Umgebungsvariable, die der Go-Toolchain angibt, woher Module heruntergeladen werden sollen. Standardmäßig (seit Go 1.14) hat sie den Wert:
GOPROXY=https://proxy.golang.org,direct
Der Wert, getrennt durch Kommas, ist eine Liste von Quellen, die Go der Reihe nach durchgeht. direct bedeutet „direkt aus VCS (git, svn, hg) herunterladen, wenn der Proxy 404 oder 410 zurückgibt“. Wenn der Proxy physisch nicht verfügbar ist (Timeout, nicht 404), wechselt Go nicht zur nächsten Quelle — es hängt einfach oder schlägt beim Timeout fehl. Dies ist ein entscheidender Punkt, den viele nicht verstehen: Der Fallback-Mechanismus funktioniert nur für „Modul nicht gefunden“ und nicht für „Netzwerk nicht verfügbar“.
Neben proxy.golang.org gibt es öffentliche Mirrors, die als Alternativen verwendet werden können:
| GOPROXY-Server | URL | Besonderheit |
|---|---|---|
| Google offiziell | proxy.golang.org | Wird häufig in geschlossenen Netzwerken blockiert |
| goproxy.cn | goproxy.cn | Mirror von der chinesischen Community, stabil verfügbar |
| Astra (goproxy.io) | goproxy.io | Alternativer globaler Mirror |
| Athens (selbst gehostet) | eigener Server | Vollständige Kontrolle, geeignet für Unternehmensmodule-Cache |
GOPROXY-Konfiguration: funktionierende Konfigurationen
Go-Umgebungsvariablen können temporär (für die Sitzung) oder dauerhaft über go env -w festgelegt werden, was die Werte in einer Go-Konfigurationsdatei speichert (normalerweise ~/.config/go/env auf Linux/macOS und %APPDATA%\go\env auf Windows).
Dauerhafte Konfiguration (empfohlen):
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Überprüfen Sie den aktuellen Wert:
go env GOPROXY
Wenn mehrere Mirrors mit Backup benötigt werden:
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
Ein wichtiger Hinweis: Wenn der erste Proxy in der Liste mit einem Timeout antwortet und nicht mit einem HTTP-Fehler, kann der Wechsel zur nächsten Quelle bis zu einer Minute für jedes Modul in Anspruch nehmen — das beeinträchtigt die Build-Geschwindigkeit in CI. Daher, wenn das Netzwerk physisch nicht zum ersten Proxy gelangt, ist es besser, ihn sofort aus der Liste zu entfernen oder den Netzwerkzugang über einen Proxy-Server einzurichten (siehe Abschnitt unten), anstatt sich auf den Fallback zu verlassen.
Wenn Sie den Zugriff auf externe Proxys vollständig deaktivieren und nur aus dem lokalen Cache oder direkt aus VCS arbeiten möchten:
go env -w GOPROXY=direct
GOPRIVATE, GONOSUMCHECK und GOSUMDB
Wenn ein Modul in einem internen Git-Repository (unternehmensinternes GitLab, Bitbucket Server, selbst gehostetes Gitea) liegt, wird Go dennoch standardmäßig versuchen, es über den öffentlichen GOPROXY zu überprüfen und den Hash über GOSUMDB abzugleichen — was nicht möglich ist, da der private Code nicht nach außen veröffentlicht wird. Das Ergebnis ist ein Fehler 410 Gone oder verifying module: checksum mismatch.
Die Lösung ist die Variable GOPRIVATE, die Go sagt: „diese Modulpfade sind privat, gehe nicht zu öffentlichen Proxys und vergleiche die Prüfziffer“.
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE setzt automatisch zwei Flags: GONOSUMCHECK (deaktiviert die Hash-Prüfung über GOSUMDB) und GOPROXY=direct für die angegebenen Pfade. Wenn eine feinere Konfiguration erforderlich ist, können sie separat festgelegt werden:
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
Für private Repositories auf GitHub muss zusätzlich git so konfiguriert werden, dass es ein Token anstelle von SSH beim Klonen über HTTPS verwendet, da die Go-Toolchain git im Hintergrund verwendet:
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
Dieser Befehl ersetzt alle HTTPS-Anfragen an github.com durch Anfragen mit Token in der URL, was es dem Go-Client ermöglicht, private Module herunterzuladen, ohne interaktiv Benutzername/Passwort eingeben zu müssen.
HTTP/HTTPS-Proxys für go get
Wenn das Büro oder der Server hinter einem Unternehmens-HTTP-Proxy (z.B. Squid) sitzt, erfährt Go nicht automatisch davon — es liest nur die Umgebungsvariablen HTTP_PROXY, HTTPS_PROXY und NO_PROXY, die für den Go net/http-Client standardmäßig sind.
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
Um dies nicht jedes Mal eingeben zu müssen, fügen Sie die Zeilen in ~/.bashrc, ~/.zshrc oder ~/.profile hinzu.
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"
Um dies dauerhaft auf Windows zu speichern, verwenden Sie setx:
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
Wichtig: NO_PROXY sollte interne Domains (internes GitLab, lokaler Athens-Server) enthalten, sonst gehen Anfragen an diese auch über den externen Proxy und schlagen mit einem Zugriffsfehler fehl.
Wenn der öffentliche GOPROXY nicht aufgrund einer internen Firewall, sondern aufgrund einer Geoblockierung einer bestimmten Region nicht verfügbar ist — eine Situation, mit der Teams konfrontiert sind, deren Server in verschiedenen Ländern verteilt sind — kann anstelle des Unternehmens-HTTP-Proxys ein ausgehender Tunnel über einen externen Proxy-Server mit der gewünschten Geolokalisierung eingerichtet werden. Für solche Szenarien sind Datacenter-Proxys geeignet — sie bieten einen stabilen schnellen Kanal und vorhersehbare Latenz, was bei massiven Downloads von Abhängigkeiten in CI-Pipelines entscheidend ist.
SOCKS5-Proxys und Umgehung von Sperren
Die Variablen HTTP_PROXY/HTTPS_PROXY unterstützen nicht nur HTTP(S)-Proxys, sondern auch SOCKS5 — seit Go 1.10+ kann die Standardbibliothek über das Schema socks5:// arbeiten:
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
Die Variable ALL_PROXY ist universell und wird von vielen CLI-Utilities gelesen, nicht nur von Go. Wenn Sie bereits einen SOCKS5-Tunnel haben (z.B. über SSH: ssh -D 1080 user@remote-host), können Sie den gesamten Datenverkehr von go get ohne zusätzliche Serverkonfiguration darüber leiten.
Um Builds aus verschiedenen Regionen zu testen (z.B. um zu überprüfen, wie sich die CI-Pipeline bei Anfragen an ein regionales Paket-Mirror verhält oder wie ein externer Dienst auf Anfragen aus einem bestimmten Land reagiert), ist oft ein Kanal mit einer realen IP-Adresse erforderlich, die einem normalen Benutzer ähnelt und nicht einem Rechenzentrum. In solchen Fällen werden residential Proxys gewählt — sie unterliegen seltener automatischen Einschränkungen auf der Serverseite von Paketverteilern oder privaten Paketregistern.
Überprüfen Sie, ob der Proxy tatsächlich von Go verwendet wird, können Sie mit einem einfachen Befehl mit detaillierter Ausgabe:
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
Das Flag -x druckt jeden ausgeführten Befehl, einschließlich Netzwerk-Anfragen, was hilft zu verstehen, ob go get tatsächlich über den Proxy geht oder Umgebungsvariablen ignoriert (dies geschieht, wenn die Variablen in einer anderen Terminalsitzung exportiert wurden oder nicht an den Unterprozess weitergegeben wurden).
Proxys in CI/CD und Docker
In CI-Runnern (GitHub Actions, GitLab CI, Jenkins) müssen Umgebungsvariablen explizit über die Job-Einstellungen weitergegeben werden, und man sollte sich nicht auf die lokale .bashrc verlassen, die im Container nicht gelesen wird.
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 (mehrstufiger Build):
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 .
Die Build-Argumente werden beim Aufruf von docker build übergeben:
docker build --build-arg HTTP_PROXY=http://user:password@proxy-host:3128 \ --build-arg HTTPS_PROXY=http://user:password@proxy-host:3128 \ -t myapp .
Wenn der Build parallel auf mehreren Runnern erfolgt und eine IP-Sperre durch das Modul-Mirror aufgrund einer großen Anzahl gleichzeitiger Anfragen vermieden werden soll (was bei selbst gehosteten Athens-Proxys unter hoher Last vorkommen kann), ist es nützlich, ausgehende Anfragen über IP-Rotation zu verteilen. Um die Last gleichmäßig zu verteilen und Rate-Limits von der Proxy-Serverseite des Modul-Mirrors zu vermeiden, werden häufig Datacenter-Proxys verwendet — sie bieten eine niedrige Latenz, was für CI wichtig ist, wo jede zusätzliche Sekunde mit der Anzahl der Jobs multipliziert wird.
Häufige Fehler und deren Lösungen
| Fehler | Ursache | Lösung |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org ist aus dem Netzwerk nicht erreichbar | GOPROXY auf einen Mirror ändern oder HTTP_PROXY konfigurieren |
410 Gone |
Privates Modul ist für den öffentlichen Proxy nicht verfügbar | GOPRIVATE für den benötigten Modulpfad konfigurieren |
checksum mismatch |
GOSUMDB versucht, ein privates Modul zu überprüfen | Über GONOSUMDB oder GOSUMDB=off deaktivieren |
x509: certificate signed by unknown authority |
Unternehmensproxy ersetzt TLS-Zertifikat (MITM) | Fügen Sie das Unternehmensstammzertifikat in den Systemstore ein |
repository not found |
Kein Zugriffstoken für privates Git-Repository vorhanden | Git config url.insteadOf mit Token konfigurieren |
| Proxy-Variablen werden ignoriert | Export wurde in einer anderen Shell/Sitzung durchgeführt | Überprüfen Sie mit env | grep PROXY in derselben Sitzung, in der go ausgeführt wird |
Besonders erwähnenswert sind MITM-Proxys (unternehmensinterne Squid/Zscaler mit Zertifikatsersetzung): Wenn ein solcher Proxy HTTPS-Datenverkehr zur Analyse abfängt, vertraut der Go-Client seinem selbstsignierten Zertifikat nicht, was zu einem x509-Fehler führt. Die Lösung besteht darin, das Unternehmensstammzertifikat im PEM-Format zu exportieren und in die Variable einzufügen:
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
Diese Variable wird vom Go-Runtime beim Überprüfen der TLS-Kette gelesen und ermöglicht die Arbeit über einen Unternehmens-MITM-Proxy, ohne die Zertifikatsprüfung vollständig zu deaktivieren (was aus Sicherheitsgründen nicht ratsam ist).
Fazit
Wenn Go-Module nicht heruntergeladen werden, reichen in 90% der Fälle drei Schritte aus: einen funktionierenden GOPROXY festlegen (öffentliches Mirror anstelle des blockierten proxy.golang.org), GOPRIVATE für interne Repositories hinzufügen und HTTP_PROXY/HTTPS_PROXY festlegen, wenn das Netzwerk nur über einen Unternehmensproxy nach außen geht. Für CI/CD müssen diese Variablen explizit über Umgebungsvariablen für Jobs oder Build-Argumente in Docker übergeben werden und nicht auf lokale Konfigurationen des Entwicklers vertraut werden.
Wenn die Ursache für die Fehler die Geoblockierung des Modul-Mirrors oder Rate-Limits von der Proxy-Serverseite bei parallelem Build in CI ist, sollte der ausgehende Datenverkehr über einen stabilen externen Kanal geleitet werden. Für solche Aufgaben sind Datacenter-Proxys gut geeignet — niedrige Latenz und vorhersehbare Bandbreite sind entscheidend bei massiven Downloads von Abhängigkeiten. Und wenn es darum geht, normalen Benutzerverkehr bei der Überprüfung der Erreichbarkeit externer Dienste aus verschiedenen Regionen zu emulieren, sind residential Proxys geeignet — sie lösen seltener Verdacht bei den Schutzsystemen auf der Seite der Paketverteilungsserver aus.