← Retour au blog

Les modules Go ne se téléchargent pas : configuration de GOPROXY, GOPRIVATE et du proxy HTTP pour go get

Guide étape par étape pour configurer GOPROXY, GOPRIVATE et un proxy réseau pour go get - pour ceux dont les modules Go ne se téléchargent pas derrière un pare-feu d'entreprise ou dans CI/CD.

📅20 novembre 2026

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 get utilise 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.