La commande go get se fige, échoue avec un timeout ou renvoie dial tcp: i/o timeout — une situation familière pour les développeurs derrière un pare-feu d'entreprise, dans un réseau fermé ou lorsqu'ils travaillent avec des dépôts GitLab/GitHub privés. Dans 90 % des cas, la raison est une mauvaise configuration de GOPROXY, l'absence de GOPRIVATE ou le blocage de l'accès direct à proxy.golang.org par un pare-feu. Voyons comment résoudre cela correctement.
Pourquoi les modules Go ne se téléchargent pas
Depuis la version Go 1.13, le système de modules se connecte par défaut au proxy public proxy.golang.org et au serveur de vérification des sommes sum.golang.org. Si les deux services sont bloqués au niveau réseau (ce qui est typique en Russie, en Chine et dans des segments d'entreprise avec des restrictions), la commande go build ou go mod tidy se figera jusqu'au timeout, puis renverra une erreur :
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
Il existe trois scénarios typiques qui empêchent le téléchargement des modules :
- Blocage réseau — le fournisseur ou le pare-feu d'entreprise bloque l'accès à l'infrastructure Google, sur laquelle reposent proxy.golang.org et sum.golang.org.
- Dépôts privés — le module se trouve dans un GitLab/Bitbucket interne, et le GOPROXY public ne peut physiquement pas y accéder, tout en essayant de vérifier sa somme de contrôle sur sum.golang.org, ce qui ne devrait pas être le cas.
- Serveur proxy dans le réseau sans variables d'environnement configurées — le trafic sortant passe uniquement par un proxy HTTP/SOCKS5, mais Go n'en est pas informé, car
go getutilise le client net/http standard, qui lit les variables d'environnement et non les paramètres système du proxy du navigateur.
Nous allons examiner chaque cas avec des commandes spécifiques et des fichiers de configuration.
Qu'est-ce que GOPROXY et comment ça fonctionne
GOPROXY est une variable d'environnement qui indique à l'outil Go d'où télécharger les modules. Par défaut (à partir de Go 1.14), sa valeur est :
GOPROXY=https://proxy.golang.org,direct
La valeur séparée par des virgules est une liste de sources que Go parcourt dans l'ordre. direct signifie « télécharger directement depuis VCS (git, svn, hg), si le proxy renvoie 404 ou 410 ». Si le proxy est physiquement inaccessible (timeout, pas 404), Go ne passe pas à la source suivante — il se fige ou échoue à cause du timeout. C'est un point clé que beaucoup ne comprennent pas : le mécanisme de fallback ne fonctionne que pour « module non trouvé », et non pour « réseau inaccessible ».
En plus de proxy.golang.org, il existe des miroirs publics qui peuvent être utilisés comme alternative :
| Serveur GOPROXY | URL | Particularité |
|---|---|---|
| Google officiel | proxy.golang.org | Souvent bloqué dans les réseaux fermés |
| goproxy.cn | goproxy.cn | Miroir de la communauté chinoise, disponible de manière stable |
| Astra (goproxy.io) | goproxy.io | Miroir global alternatif |
| Athens (auto-hébergé) | serveur personnel | Contrôle total, adapté pour le cache de modules d'entreprise |
Configuration de GOPROXY : configurations fonctionnelles
Les variables d'environnement Go peuvent être définies temporairement (pour la session) ou de manière permanente via go env -w, ce qui enregistre les valeurs dans le fichier de configuration Go (généralement ~/.config/go/env sur Linux/macOS et %APPDATA%\go\env sur Windows).
Configuration permanente (recommandée) :
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Vérifiez la valeur actuelle :
go env GOPROXY
Si vous avez besoin de plusieurs miroirs avec un backup :
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
Un point important : si le premier proxy de la liste répond par un timeout, et non par une erreur HTTP, le passage à la source suivante peut prendre jusqu'à une minute pour chaque module — cela tue la vitesse de construction dans CI. Donc, si le réseau n'atteint physiquement pas le premier proxy, il est préférable de l'enlever de la liste ou de configurer l'accès réseau via un serveur proxy (voir la section ci-dessous), plutôt que de compter sur le fallback.
Si vous souhaitez désactiver complètement l'accès aux proxies externes et travailler uniquement à partir du cache local ou directement depuis VCS :
go env -w GOPROXY=direct
GOPRIVATE, GONOSUMCHECK et GOSUMDB
Lorsque le module se trouve dans un dépôt Git interne (GitLab d'entreprise, Bitbucket Server, Gitea auto-hébergé), Go tentera tout de même par défaut de le vérifier via le GOPROXY public et de comparer le hachage via GOSUMDB — ce qui est impossible, car le code privé n'est pas publié à l'extérieur. Le résultat est une erreur 410 Gone ou verifying module: checksum mismatch.
La solution est la variable GOPRIVATE, qui indique à Go : « ces chemins de modules sont privés, ne va pas les chercher dans le proxy public et ne vérifie pas la somme de contrôle ».
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE active automatiquement deux flags : GONOSUMCHECK (désactive la vérification du hachage via GOSUMDB) et GOPROXY=direct pour les chemins spécifiés. Mais si une configuration plus fine est nécessaire, vous pouvez les définir séparément :
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
Pour les dépôts privés sur GitHub, il est également nécessaire de configurer git pour utiliser un token au lieu de SSH lors du clonage via HTTPS, car l'outil Go utilise git en arrière-plan :
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
Cette commande remplace toutes les requêtes HTTPS vers github.com par une requête avec le token dans l'URL, ce qui permet au client Go de télécharger des modules privés sans saisie interactive du nom d'utilisateur/mot de passe.
Proxy HTTP/HTTPS pour go get
Si le bureau ou le serveur est derrière un proxy HTTP d'entreprise (par exemple, Squid), Go ne le saura pas automatiquement — il ne lit que les variables d'environnement HTTP_PROXY, HTTPS_PROXY et NO_PROXY, qui sont standards pour le client 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
Pour ne pas avoir à le saisir à chaque fois, ajoutez ces lignes dans ~/.bashrc, ~/.zshrc ou ~/.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"
Pour une sauvegarde permanente sur Windows, utilisez setx :
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
Important : NO_PROXY doit inclure les domaines internes (GitLab interne, serveur Athens local), sinon les requêtes vers eux passeront également par le proxy externe et échoueront avec une erreur d'accès.
Si le GOPROXY public n'est pas accessible non pas à cause d'un pare-feu interne, mais à cause d'une géoblocage d'une région spécifique — une situation rencontrée par des équipes dont les serveurs sont répartis dans différents pays — au lieu d'un proxy HTTP d'entreprise, vous pouvez établir un tunnel sortant via un serveur proxy externe avec la géolocalisation requise. Pour de tels scénarios, des proxies de datacenter sont appropriés — ils offrent un canal stable et rapide et une latence prévisible, ce qui est critique lors du téléchargement massif de dépendances dans un pipeline CI.
Proxy SOCKS5 et contournement des blocages
Les variables HTTP_PROXY/HTTPS_PROXY prennent en charge non seulement les proxies HTTP(S), mais aussi SOCKS5 — à partir de Go 1.10+, la bibliothèque standard peut fonctionner via le schéma 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
La variable ALL_PROXY est universelle, elle est lue par de nombreux utilitaires CLI, pas seulement Go. Si vous avez déjà un tunnel SOCKS5 (par exemple, via SSH : ssh -D 1080 user@remote-host), vous pouvez faire passer tout le trafic go get à travers sans configurations supplémentaires sur le serveur.
Pour tester la construction depuis différentes régions (par exemple, pour voir comment le pipeline CI se comporte lors d'une requête à un miroir régional de paquets ou comment un service externe réagit aux requêtes d'un pays spécifique), il est souvent nécessaire d'avoir un canal avec une adresse IP réelle, semblable à celle d'un utilisateur normal, et non d'un datacenter. Dans de tels cas, on choisit des proxies résidentiels — ils sont moins susceptibles de déclencher des restrictions automatiques du côté des serveurs de distribution de modules ou des registres de paquets privés.
Pour vérifier que le proxy est réellement utilisé par Go, vous pouvez exécuter une simple commande avec une sortie détaillée :
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
Le flag -x imprime chaque commande exécutée, y compris les requêtes réseau, ce qui aide à comprendre si go get passe réellement par le proxy ou ignore les variables d'environnement (ce qui se produit si les variables sont exportées dans une autre session de terminal ou ne sont pas passées au sous-processus).
Proxy dans CI/CD et Docker
Dans les runners CI (GitHub Actions, GitLab CI, Jenkins), les variables d'environnement doivent être passées explicitement via les paramètres de job, et non compter sur le .bashrc local, qui n'est pas lu dans le conteneur.
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 (construction multi-étapes) :
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 .
Les arguments de construction sont passés lors de l'appel de 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 .
Si la construction se fait en parallèle sur plusieurs runners et qu'il faut éviter le bannissement par IP du côté du miroir de modules à cause d'un grand nombre de requêtes simultanées (ce qui arrive avec des proxies Athens auto-hébergés sous forte charge), il est utile de répartir les requêtes sortantes via une rotation d'IP. Pour une répartition uniforme de la charge et pour éviter les limites de taux du côté du serveur proxy du miroir de modules, on utilise souvent des proxies de datacenter — ils assurent une faible latence, ce qui est important pour CI, où chaque seconde supplémentaire est multipliée par le nombre de jobs.
Erreurs fréquentes et leurs solutions
| Erreur | Cause | Solution |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org inaccessible depuis le réseau | Changer GOPROXY pour un miroir ou configurer HTTP_PROXY |
410 Gone |
Le module privé n'est pas accessible au proxy public | Configurer GOPRIVATE pour le chemin du module requis |
checksum mismatch |
GOSUMDB essaie de vérifier un module privé | Désactiver via GONOSUMDB ou GOSUMDB=off |
x509: certificate signed by unknown authority |
Le proxy d'entreprise modifie le certificat TLS (MITM) | Ajouter le certificat racine de l'entreprise dans le magasin de certificats système |
repository not found |
Pas de token d'accès pour le dépôt git privé | Configurer git config url.insteadOf avec le token |
| Les variables proxy sont ignorées | L'exportation a été faite dans une autre shell/session | Vérifiez via env | grep PROXY dans la même session où go est exécuté |
Il convient de mentionner séparément les proxies MITM (Squid/Zscaler d'entreprise avec modification des certificats) : si un tel proxy intercepte le trafic HTTPS pour analyse, le client Go ne fait pas confiance à son certificat auto-signé, ce qui entraîne l'erreur x509. La solution consiste à exporter le certificat racine de l'entreprise au format PEM et à le spécifier dans la variable :
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
Cette variable est lue par le runtime Go lors de la vérification de la chaîne TLS et permet de travailler via un proxy MITM d'entreprise sans désactiver complètement la vérification des certificats (ce qui n'est pas recommandé pour des raisons de sécurité).
Conclusion
Si les modules Go ne se téléchargent pas, dans 90 % des cas, trois étapes suffisent : définir un GOPROXY fonctionnel (un miroir public à la place de proxy.golang.org bloqué), ajouter GOPRIVATE pour les dépôts internes et spécifier HTTP_PROXY/HTTPS_PROXY si le réseau sort uniquement via un proxy d'entreprise. Pour CI/CD, ces variables doivent être passées explicitement via les variables d'environnement de job ou les arguments de construction Docker, et non compter sur les configurations locales du développeur.
Si la cause des échecs est la géoblocage du miroir de modules ou le rate-limit du côté du serveur proxy lors de constructions parallèles dans CI, il est préférable de faire passer le trafic sortant par un canal externe stable. Pour de telles tâches, les proxies de datacenter sont bien adaptés — une faible latence et une bande passante prévisible sont critiques lors du téléchargement massif de dépendances. Et si vous devez émuler le trafic d'un utilisateur normal lors de tests de disponibilité de services externes depuis différentes régions, les proxies résidentiels sont appropriés — ils suscitent moins de soupçons auprès des systèmes de protection du côté des serveurs de distribution de paquets.