← Voltar ao blog

Go módulos não baixam: configurando GOPROXY, GOPRIVATE e proxy HTTP para go get

Instruções passo a passo para configurar GOPROXY, GOPRIVATE e proxy de rede para go get — para aqueles que não conseguem baixar módulos Go atrás do firewall corporativo ou em CI/CD.

📅20 de novembro de 2026

O comando go get trava, falha com um timeout ou retorna dial tcp: i/o timeout — uma situação familiar para desenvolvedores atrás de firewalls corporativos, em redes fechadas ou ao trabalhar com repositórios privados do GitLab/GitHub. Em 90% dos casos, a causa está na configuração incorreta de GOPROXY, na ausência de GOPRIVATE ou na bloqueio de acesso direto ao proxy.golang.org pelo firewall. Vamos analisar como corrigir isso corretamente.

Por que os módulos Go não estão sendo baixados

A partir da versão Go 1.13, o sistema de módulos por padrão se conecta ao proxy público proxy.golang.org e ao servidor de verificação de somas sum.golang.org. Se ambos os serviços estiverem bloqueados a nível de rede (o que é típico na Rússia, China e segmentos corporativos com restrições), o comando go build ou go mod tidy ficará travado até o timeout e depois retornará um erro:

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

Existem três cenários típicos que podem causar a falha no download de módulos:

  • Bloqueio de rede — o provedor ou firewall corporativo corta o acesso à infraestrutura do Google, onde estão localizados proxy.golang.org e sum.golang.org.
  • Repositórios privados — o módulo está em um GitLab/Bitbucket interno, e o GOPROXY público não consegue acessá-lo fisicamente, além de tentar verificar sua soma no sum.golang.org, embora não deva.
  • Servidor proxy na rede sem variáveis de ambiente configuradas — o tráfego externo só passa por proxies HTTP/SOCKS5, mas o Go não sabe disso, porque go get usa o cliente padrão net/http, que lê variáveis de ambiente, e não as configurações de proxy do sistema do navegador.

A seguir, vamos analisar cada caso com comandos específicos e arquivos de configuração.

O que é GOPROXY e como funciona

GOPROXY é uma variável de ambiente que indica à ferramenta Go de onde baixar os módulos. Por padrão (a partir do Go 1.14), seu valor é:

GOPROXY=https://proxy.golang.org,direct

O valor separado por vírgulas é uma lista de fontes que o Go percorre em ordem. direct significa "baixar diretamente do VCS (git, svn, hg), se o proxy retornar 404 ou 410". Se o proxy não estiver fisicamente disponível (timeout, e não 404), o Go não passa para a próxima fonte — ele simplesmente trava ou falha com um timeout. Este é um ponto chave que muitos não entendem: o mecanismo de fallback funciona apenas para "módulo não encontrado", e não para "rede indisponível".

Além do proxy.golang.org, existem espelhos públicos que podem ser usados como alternativa:

Servidor GOPROXY URL Particularidade
Google oficial proxy.golang.org Frequentemente bloqueado em redes fechadas
goproxy.cn goproxy.cn Espelho da comunidade chinesa, acessível de forma estável
Astra (goproxy.io) goproxy.io Espelho global alternativo
Athens (auto-hospedado) servidor próprio Controle total, adequado para cache corporativo de módulos

Configuração do GOPROXY: configurações funcionais

As variáveis de ambiente do Go podem ser definidas temporariamente (para a sessão) ou permanentemente através de go env -w, o que salva os valores em um arquivo de configuração do Go (geralmente ~/.config/go/env no Linux/macOS e %APPDATA%\go\env no Windows).

Configuração permanente (recomendada):

go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.org

Verifique o valor atual:

go env GOPROXY

Se precisar de vários espelhos com fallback:

go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct

Um detalhe importante: se o primeiro proxy na lista responder com timeout, e não com um erro HTTP, a transição para a próxima fonte pode levar até um minuto para cada módulo — isso prejudica a velocidade de compilação em CI. Portanto, se a rede não consegue acessar fisicamente o primeiro proxy, é melhor removê-lo da lista ou configurar o acesso à rede através de um servidor proxy (veja a seção abaixo), em vez de contar com o fallback.

Se você quiser desativar completamente o acesso a proxies externos e trabalhar apenas a partir do cache local ou diretamente do VCS:

go env -w GOPROXY=direct

GOPRIVATE, GONOSUMCHECK e GOSUMDB

Quando um módulo está em um repositório Git interno (GitLab corporativo, Bitbucket Server, Gitea auto-hospedado), o Go ainda tentará verificar por padrão através do GOPROXY público e comparar o hash através do GOSUMDB — o que é impossível, pois o código privado não é publicado externamente. O resultado é um erro 410 Gone ou verifying module: checksum mismatch.

A solução é a variável GOPRIVATE, que informa ao Go: "esses caminhos de módulos são privados, não vá atrás deles no proxy público e não verifique a soma".

go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*

O GOPRIVATE automaticamente define duas flags: GONOSUMCHECK (desativa a verificação de hash através do GOSUMDB) e GOPROXY=direct para os caminhos especificados. Mas se uma configuração mais detalhada for necessária, você pode defini-las separadamente:

go env -w GONOSUMCHECK=1
go env -w GOSUMDB=off
go env -w GONOSUMDB=gitlab.company.com/*

Para repositórios privados no GitHub, você também precisa configurar o git para usar um token em vez de SSH ao clonar via HTTPS, pois a ferramenta Go utiliza o git por baixo dos panos:

git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

Este comando substitui todas as chamadas HTTPS para github.com por solicitações com o token na URL, permitindo que o cliente Go baixe módulos privados sem a necessidade de entrada interativa de login/senha.

Proxies HTTP/HTTPS para go get

Se o escritório ou servidor estiver atrás de um proxy HTTP corporativo (por exemplo, Squid), o Go não saberá disso automaticamente — ele lê apenas as variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY, que são padrão para o cliente net/http do Go.

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

Para não precisar digitar isso toda vez, adicione as linhas em ~/.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"

Para salvar permanentemente no Windows, use setx:

setx HTTP_PROXY "http://user:password@proxy-host:3128"
setx HTTPS_PROXY "http://user:password@proxy-host:3128"

Importante: NO_PROXY deve incluir domínios internos (GitLab interno, servidor Athens local), caso contrário, as solicitações para eles também passarão pelo proxy externo e falharão com um erro de acesso.

Se o GOPROXY público não estiver acessível não devido a um firewall interno, mas devido a geobloqueio de uma região específica — uma situação que equipes enfrentam quando seus servidores estão distribuídos em diferentes países — em vez de um proxy HTTP corporativo, você pode estabelecer um túnel de saída através de um servidor proxy externo com a geolocalização necessária. Para tais cenários, proxies de data center são adequados — eles oferecem um canal rápido e estável e uma latência previsível, o que é crítico ao carregar dependências em massa em um pipeline CI.

Proxies SOCKS5 e contorno de bloqueios

As variáveis HTTP_PROXY/HTTPS_PROXY suportam não apenas proxies HTTP(S), mas também SOCKS5 — a partir do Go 1.10+, a biblioteca padrão pode trabalhar através do esquema 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

A variável ALL_PROXY é universal, e muitas ferramentas CLI, não apenas o Go, a leem. Se você já tem um túnel SOCKS5 (por exemplo, via SSH: ssh -D 1080 user@remote-host), você pode direcionar todo o tráfego do go get através dele sem configurações adicionais no servidor.

Para testar a compilação de diferentes regiões (por exemplo, para verificar como o pipeline CI se comporta ao solicitar um espelho regional de pacotes ou como um serviço externo reage a solicitações de um país específico), muitas vezes é necessário um canal com um IP real, semelhante ao de um usuário comum, e não de um data center. Nesses casos, proxies residenciais são escolhidos — eles raramente são afetados por restrições automáticas do lado dos servidores de distribuição de módulos ou repositórios de pacotes privados.

Para verificar se o proxy está realmente sendo usado pelo Go, você pode usar um comando simples com saída detalhada:

GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin

A flag -x imprime cada comando executado, incluindo solicitações de rede, o que ajuda a entender se o go get está realmente passando pelo proxy ou ignorando as variáveis de ambiente (isso acontece se as variáveis foram exportadas em outra sessão de terminal ou não foram passadas para subprocessos).

Proxies em CI/CD e Docker

Em runners CI (GitHub Actions, GitLab CI, Jenkins), as variáveis de ambiente precisam ser passadas explicitamente através das configurações do job, e não confiar no local .bashrc, que não é lido dentro do contêiner.

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 (compilação em múltiplas etapas):

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 .

Os argumentos de construção são passados ao chamar 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 .

Se a construção estiver ocorrendo em paralelo em vários runners e for necessário evitar o bloqueio por IP do espelho de módulos devido ao grande número de solicitações simultâneas (o que ocorre com proxies Athens auto-hospedados sob alta carga), é útil distribuir as solicitações de saída através da rotação de IP. Para uma distribuição uniforme da carga e para evitar o rate-limit do lado do servidor proxy do espelho de módulos, frequentemente são utilizados proxies de data center — eles garantem baixa latência, o que é importante para CI, onde cada segundo extra é multiplicado pelo número de jobs.

Erros comuns e suas soluções

Erro Causa Solução
dial tcp: i/o timeout proxy.golang.org não está acessível a partir da rede Mudar o GOPROXY para um espelho ou configurar o HTTP_PROXY
410 Gone Módulo privado não acessível pelo proxy público Configurar o GOPRIVATE para o caminho do módulo necessário
checksum mismatch GOSUMDB está tentando verificar um módulo privado Desativar através do GONOSUMDB ou GOSUMDB=off
x509: certificate signed by unknown authority Proxy corporativo substitui o certificado TLS (MITM) Adicionar o certificado raiz da empresa ao armazenamento de sistema
repository not found Sem token de acesso para repositório git privado Configurar git config url.insteadOf com o token
Variáveis de proxy ignoradas Exportação feita em outra shell/sessão Verificar através de env | grep PROXY na mesma sessão onde o go é executado

É importante mencionar sobre proxies MITM (Squid/Zscaler corporativos com substituição de certificados): se tal proxy intercepta o tráfego HTTPS para análise, o cliente Go não confia em seu certificado autoassinado, resultando em um erro x509. A solução é exportar o certificado raiz da empresa no formato PEM e especificá-lo na variável:

export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem

Esta variável é lida pelo runtime do Go ao verificar a cadeia TLS e permite trabalhar através do proxy MITM corporativo sem desativar completamente a verificação de certificados (o que não deve ser feito por razões de segurança).

Conclusão

Se os módulos Go não estão sendo baixados, em 90% dos casos, três passos são suficientes: definir um GOPROXY funcional (um espelho público em vez do proxy.golang.org bloqueado), adicionar GOPRIVATE para repositórios internos e especificar HTTP_PROXY/HTTPS_PROXY, se a rede só acessar externamente através de um proxy corporativo. Para CI/CD, essas variáveis precisam ser passadas explicitamente através de variáveis de ambiente do job ou argumentos de construção do Docker, e não confiar nas configurações locais do desenvolvedor.

Se a causa das falhas for o geobloqueio do espelho de módulos ou rate-limit do lado do servidor proxy durante a construção paralela em CI, é aconselhável direcionar o tráfego de saída através de um canal externo estável. Para tais tarefas, proxies de data center são uma boa opção — baixa latência e largura de banda previsível são críticas ao carregar dependências em massa. E se for necessário emular o tráfego de um usuário comum ao testar a acessibilidade de serviços externos de diferentes regiões, proxies residenciais são adequados — eles raramente levantam suspeitas nos sistemas de proteção do lado dos servidores de distribuição de pacotes.