← Volver al blog

No se descargan los módulos Go: configuración de GOPROXY, GOPRIVATE y proxy HTTP para go get

Instrucciones paso a paso para configurar GOPROXY, GOPRIVATE y un proxy de red para go get, para aquellos que no pueden descargar módulos de Go detrás de un firewall corporativo o en CI/CD.

📅20 de noviembre de 2026

El comando go get se queda colgado, falla con un timeout o devuelve dial tcp: i/o timeout — una situación familiar para los desarrolladores detrás de un firewall corporativo, en una red cerrada o al trabajar con repositorios privados de GitLab/GitHub. En el 90% de los casos, la causa es una configuración incorrecta de GOPROXY, la ausencia de GOPRIVATE o el bloqueo del acceso directo a proxy.golang.org por parte de un firewall. Vamos a ver cómo solucionarlo correctamente.

Por qué no se descargan los módulos de Go

Desde la versión Go 1.13, el sistema de módulos por defecto se dirige al proxy público proxy.golang.org y al servidor de verificación de sumas sum.golang.org. Si ambos servicios están bloqueados a nivel de red (lo cual es típico en Rusia, China y segmentos corporativos con restricciones), el comando go build o go mod tidy se quedará colgado hasta que se agote el tiempo de espera, y luego mostrará un error:

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

Hay tres escenarios típicos que causan que la descarga de módulos falle:

  • Bloqueo de red — el proveedor o el firewall corporativo restringen el acceso a la infraestructura de Google, donde se alojan proxy.golang.org y sum.golang.org.
  • Repositorios privados — el módulo se encuentra en un GitLab/Bitbucket interno, y el GOPROXY público no puede acceder a él físicamente, además de intentar verificar su suma en sum.golang.org, aunque no debería.
  • Proxy en la red sin variables de entorno configuradas — el tráfico hacia el exterior solo pasa a través de un proxy HTTP/SOCKS5, pero Go no lo sabe, porque go get utiliza el cliente net/http estándar, que lee las variables de entorno y no la configuración del proxy del sistema desde el navegador.

A continuación, analizaremos cada caso con comandos específicos y archivos de configuración.

Qué es GOPROXY y cómo funciona

GOPROXY es una variable de entorno que indica a las herramientas de Go desde dónde descargar módulos. Por defecto (a partir de Go 1.14), su valor es:

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

El valor separado por comas es una lista de fuentes que Go revisa en orden. direct significa "descargar directamente desde VCS (git, svn, hg), si el proxy devuelve 404 o 410". Si el proxy no está disponible físicamente (timeout, no 404), Go no pasa a la siguiente fuente — simplemente se queda colgado o falla por timeout. Este es un punto clave que muchos no entienden: el mecanismo de fallback solo funciona para "módulo no encontrado", y no para "red no disponible".

Además de proxy.golang.org, hay espejos públicos que se pueden usar como alternativa:

Servidor GOPROXY URL Característica
Google oficial proxy.golang.org A menudo bloqueado en redes cerradas
goproxy.cn goproxy.cn Espejo de la comunidad china, disponible de manera estable
Astra (goproxy.io) goproxy.io Espejo global alternativo
Athens (autoalojado) servidor propio Control total, adecuado para caché de módulos corporativos

Configuración de GOPROXY: configuraciones funcionales

Las variables de entorno de Go se pueden establecer temporalmente (para la sesión) o permanentemente a través de go env -w, lo que guarda los valores en el archivo de configuración de Go (normalmente ~/.config/go/env en Linux/macOS y %APPDATA%\go\env en Windows).

Configuración permanente (recomendada):

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

Verificar el valor actual:

go env GOPROXY

Si se necesitan varios espejos como respaldo:

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

Un matiz importante: si el primer proxy en la lista responde con un timeout y no con un error HTTP, pasar a la siguiente fuente puede tardar hasta un minuto por cada módulo — esto mata la velocidad de compilación en CI. Por lo tanto, si la red no puede llegar físicamente al primer proxy, es mejor eliminarlo de la lista o configurar el acceso a la red a través de un servidor proxy (ver sección a continuación), en lugar de confiar en el fallback.

Si se desea desactivar completamente el acceso a proxies externos y trabajar solo desde la caché local o directamente desde VCS:

go env -w GOPROXY=direct

GOPRIVATE, GONOSUMCHECK y GOSUMDB

Cuando un módulo se encuentra en un repositorio Git interno (GitLab corporativo, Bitbucket Server, Gitea autoalojado), Go aún intentará verificarlo a través del GOPROXY público y comparar el hash a través de GOSUMDB — lo cual es imposible, ya que el código privado no se publica externamente. El resultado es un error 410 Gone o verifying module: checksum mismatch.

La solución es la variable GOPRIVATE, que le dice a Go: "estas rutas de módulos son privadas, no vayas a buscarlas en el proxy público y no verifiques la suma".

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

GOPRIVATE automáticamente establece dos flags: GONOSUMCHECK (desactiva la verificación del hash a través de GOSUMDB) y GOPROXY=direct para las rutas especificadas. Pero si se necesita una configuración más detallada, se pueden establecer por separado:

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

Para repositorios privados en GitHub, también es necesario configurar git para usar un token en lugar de SSH al clonar a través de HTTPS, porque las herramientas de Go utilizan git internamente:

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

Este comando reemplaza todas las solicitudes HTTPS a github.com por solicitudes con el token en la URL, lo que permite al cliente de Go descargar módulos privados sin necesidad de ingresar interactivamente el nombre de usuario/contraseña.

Proxy HTTP/HTTPS para go get

Si la oficina o el servidor está detrás de un proxy HTTP corporativo (por ejemplo, Squid), Go no lo detectará automáticamente — solo lee las variables de entorno HTTP_PROXY, HTTPS_PROXY y NO_PROXY, que son estándar para el cliente net/http de 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 no tener que escribir esto cada vez, agregue las líneas a ~/.bashrc, ~/.zshrc o ~/.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 guardar de forma permanente en Windows, use setx:

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

Importante: NO_PROXY debe incluir dominios internos (GitLab interno, servidor Athens local), de lo contrario, las solicitudes a ellos también pasarán a través del proxy externo y fallarán con un error de acceso.

Si el GOPROXY público no está disponible no por un firewall interno, sino por una geobloqueo de una región específica — una situación que enfrentan equipos cuyos servidores están dispersos en diferentes países — en lugar de un proxy HTTP corporativo, se puede establecer un túnel saliente a través de un servidor proxy externo con la geolocalización deseada. Para tales escenarios, son adecuados los proxies de centros de datos — proporcionan un canal rápido y estable y una latencia predecible, lo cual es crítico al cargar dependencias en un pipeline de CI.

Proxy SOCKS5 y eludir bloqueos

Las variables HTTP_PROXY/HTTPS_PROXY no solo admiten proxies HTTP(S), sino también SOCKS5 — a partir de Go 1.10+, la biblioteca estándar puede trabajar a través del 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

La variable ALL_PROXY es universal, la leen muchas utilidades CLI, no solo Go. Si ya tiene un túnel SOCKS5 (por ejemplo, a través de SSH: ssh -D 1080 user@remote-host), puede enviar todo el tráfico de go get a través de él sin configuraciones adicionales en el servidor.

Para probar la construcción desde diferentes regiones (por ejemplo, para verificar cómo se comporta el pipeline de CI al solicitar un espejo regional de paquetes o cómo reacciona un servicio externo a solicitudes desde un país específico), a menudo se necesita un canal con una dirección IP real, similar a la de un usuario normal, y no a la de un centro de datos. En tales casos, se eligen proxies residenciales — son menos propensos a ser bloqueados automáticamente por los servidores de distribución de módulos o registros de paquetes privados.

Para verificar que el proxy realmente está siendo utilizado por Go, se puede usar un simple comando con salida detallada:

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

La bandera -x imprime cada comando ejecutado, incluidas las solicitudes de red, lo que ayuda a entender si go get realmente pasa a través del proxy o ignora las variables de entorno (esto sucede si las variables se exportan en otra sesión de terminal o no se pasan al subproceso).

Proxy en CI/CD y Docker

En los runners de CI (GitHub Actions, GitLab CI, Jenkins), las variables de entorno deben ser pasadas explícitamente a través de la configuración del job, y no confiar en el .bashrc local, que no se lee en el contenedor.

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 (compilación multietapa):

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 .

Los argumentos de construcción se pasan al invocar 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 construcción se realiza en paralelo en varios runners y es necesario evitar el baneo por IP por parte del espejo de módulos debido a la gran cantidad de solicitudes simultáneas (lo que ocurre con proxies Athens autoalojados bajo alta carga), es útil distribuir las solicitudes salientes a través de una rotación de IP. Para una distribución uniforme de la carga y evitar el rate-limit por parte del proxy del espejo de módulos, a menudo se utilizan proxies de centros de datos — proporcionan baja latencia, lo que es importante para CI, donde cada segundo adicional se multiplica por el número de jobs.

Errores comunes y sus soluciones

Error Causa Solución
dial tcp: i/o timeout proxy.golang.org no está disponible desde la red Cambiar GOPROXY a un espejo o configurar HTTP_PROXY
410 Gone El módulo privado no está disponible para el proxy público Configurar GOPRIVATE para la ruta del módulo necesaria
checksum mismatch GOSUMDB intenta verificar un módulo privado Desactivar a través de GONOSUMDB o GOSUMDB=off
x509: certificate signed by unknown authority El proxy corporativo reemplaza el certificado TLS (MITM) Agregar el certificado raíz de la empresa al almacén de certificados del sistema
repository not found No hay token de acceso para el repositorio git privado Configurar git config url.insteadOf con el token
Las variables de proxy son ignoradas La exportación se realizó en otra shell/sesión Verificar a través de env | grep PROXY en la misma sesión donde se ejecuta go

Es importante mencionar los proxies MITM (Squid/Zscaler corporativos con reemplazo de certificados): si tal proxy intercepta el tráfico HTTPS para análisis, el cliente de Go no confía en su certificado autofirmado, lo que lleva al error x509. La solución es exportar el certificado raíz de la empresa en formato PEM y especificarlo en la variable:

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

Esta variable es leída por el runtime de Go al verificar la cadena TLS y permite trabajar a través de un proxy MITM corporativo sin desactivar completamente la verificación de certificados (lo cual no se debe hacer por razones de seguridad).

Conclusión

Si los módulos de Go no se descargan, en el 90% de los casos basta con tres pasos: establecer un GOPROXY funcional (un espejo público en lugar del bloqueado proxy.golang.org), agregar GOPRIVATE para repositorios internos y especificar HTTP_PROXY/HTTPS_PROXY si la red sale al exterior solo a través de un proxy corporativo. Para CI/CD, estas variables deben ser pasadas explícitamente a través de variables de entorno del job o argumentos de construcción de Docker, y no confiar en las configuraciones locales del desarrollador.

Si la causa de los fallos es la geobloqueo del espejo de módulos o el rate-limit por parte del servidor proxy durante la construcción paralela en CI, es recomendable dirigir el tráfico saliente a través de un canal externo estable. Para tales tareas, son adecuados los proxies de centros de datos — la baja latencia y el ancho de banda predecible son críticos al cargar dependencias masivamente. Y si se necesita emular el tráfico de un usuario normal al probar la disponibilidad de servicios externos desde diferentes regiones, los proxies residenciales son una buena opción — son menos propensos a levantar sospechas en los sistemas de protección de los servidores de distribución de paquetes.