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 getutiliza 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.