Команда go get зависает, падает с таймаутом или выдаёт dial tcp: i/o timeout — знакомая ситуация для разработчиков за корпоративным файрволом, в закрытой сети или при работе с приватными GitLab/GitHub-репозиториями. В 90% случаев причина в неправильной настройке GOPROXY, отсутствии GOPRIVATE или блокировке прямого доступа к proxy.golang.org сетевым экраном. Разберём, как это чинить правильно.
Почему Go-модули не скачиваются
С версии Go 1.13 модульная система по умолчанию обращается к публичному прокси proxy.golang.org и серверу проверки сумм sum.golang.org. Если оба сервиса заблокированы на уровне сети (это типично для РФ, Китая и корпоративных сегментов с ограничениями), команда go build или go mod tidy будет висеть до таймаута, а потом выдаст ошибку:
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
Есть три типичных сценария, из-за которых ломается скачивание модулей:
- Сетевая блокировка — провайдер или корпоративный файрвол режет доступ к Google-инфраструктуре, на которой держатся proxy.golang.org и sum.golang.org.
- Приватные репозитории — модуль лежит во внутреннем GitLab/Bitbucket, и публичный GOPROXY физически не может до него достучаться, а заодно пытается проверить его чек-сумму на sum.golang.org, хотя не должен.
- Прокси-сервер в сети без настроенных переменных окружения — трафик наружу идёт только через HTTP/SOCKS5-прокси, но Go об этом не знает, потому что
go getиспользует стандартный net/http клиент, который читает переменные окружения, а не системные настройки прокси из браузера.
Дальше разберём каждый случай с конкретными командами и файлами конфигурации.
Что такое GOPROXY и как он работает
GOPROXY — это переменная окружения, которая указывает Go-инструментарию, откуда скачивать модули. По умолчанию (начиная с Go 1.14) её значение:
GOPROXY=https://proxy.golang.org,direct
Значение через запятую — это список источников, которые Go перебирает по порядку. direct означает «скачивать напрямую из VCS (git, svn, hg), если прокси вернул 404 или 410». Если прокси недоступен физически (таймаут, а не 404), Go не переходит к следующему источнику — он просто зависает или падает по таймауту. Это ключевой момент, который многие не понимают: механизм fallback работает только для «модуль не найден», а не для «сеть недоступна».
Помимо proxy.golang.org есть публичные зеркала, которые можно использовать как альтернативу:
| GOPROXY-сервер | URL | Особенность |
|---|---|---|
| Google официальный | proxy.golang.org | Часто заблокирован в закрытых сетях |
| goproxy.cn | goproxy.cn | Зеркало от китайского сообщества, стабильно доступно |
| Astra (goproxy.io) | goproxy.io | Альтернативное глобальное зеркало |
| Athens (self-hosted) | свой сервер | Полный контроль, подходит для корпоративного кэша модулей |
Настройка GOPROXY: рабочие конфигурации
Переменные окружения Go можно задать временно (на сессию) или постоянно через go env -w, что сохраняет значения в файл конфигурации Go (обычно ~/.config/go/env на Linux/macOS и %APPDATA%\go\env на Windows).
Постоянная настройка (рекомендуется):
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Проверить текущее значение:
go env GOPROXY
Если нужно несколько зеркал с резервом:
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
Важный нюанс: если первый прокси в списке отвечает таймаутом, а не HTTP-ошибкой, переход к следующему источнику может занять до минуты на каждый модуль — это убивает скорость сборки в CI. Поэтому если сеть физически не достаёт до первого прокси, лучше сразу убрать его из списка или настроить сетевой доступ через прокси-сервер (см. раздел ниже), а не полагаться на fallback.
Если хочется полностью отключить обращение к внешним прокси и работать только из локального кэша или напрямую из VCS:
go env -w GOPROXY=direct
GOPRIVATE, GONOSUMCHECK и GOSUMDB
Когда модуль лежит во внутреннем Git-репозитории (корпоративный GitLab, Bitbucket Server, self-hosted Gitea), Go всё равно по умолчанию попытается проверить его через публичный GOPROXY и сверить хэш через GOSUMDB — а это невозможно, потому что приватный код не публикуется наружу. Результат — ошибка 410 Gone или verifying module: checksum mismatch.
Решение — переменная GOPRIVATE, которая говорит Go: «эти пути модулей — приватные, не ходи за ними в публичный прокси и не сверяй чек-сумму».
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE автоматически выставляет два флага сразу: GONOSUMCHECK (отключает проверку хэша через GOSUMDB) и GOPROXY=direct для указанных путей. Но если нужна более тонкая настройка, можно задать их отдельно:
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
Для приватных репозиториев на GitHub дополнительно нужно настроить git на использование токена вместо SSH при клонировании через HTTPS, потому что Go-инструментарий использует git под капотом:
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
Эта команда подменяет все HTTPS-обращения к github.com на запрос с токеном в URL, что позволяет Go-клиенту скачивать приватные модули без интерактивного ввода логина/пароля.
HTTP/HTTPS-прокси для go get
Если офис или сервер сидит за корпоративным HTTP-прокси (например, Squid), Go не узнает об этом автоматически — он читает только переменные окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY, стандартные для 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
Чтобы не прописывать это каждый раз, добавьте строки в ~/.bashrc, ~/.zshrc или ~/.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"
Для постоянного сохранения на Windows используйте setx:
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
Важно: NO_PROXY должен включать внутренние домены (внутренний GitLab, локальный Athens-сервер), иначе запросы к ним тоже пойдут через внешний прокси и будут падать с ошибкой доступа.
Если публичный GOPROXY недоступен не из-за внутреннего файрвола, а из-за геоблокировки конкретного региона — ситуация, с которой сталкиваются команды, у которых серверы разнесены по разным странам — вместо корпоративного HTTP-прокси можно поднять исходящий туннель через внешний прокси-сервер с нужной геолокацией. Для таких сценариев подходят прокси дата-центров — они дают стабильный быстрый канал и предсказуемую задержку, что критично при массовой загрузке зависимостей в CI-пайплайне.
SOCKS5-прокси и обход блокировок
Переменные HTTP_PROXY/HTTPS_PROXY поддерживают не только HTTP(S)-прокси, но и SOCKS5 — начиная с Go 1.10+ стандартная библиотека умеет работать через схему 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
Переменная ALL_PROXY — универсальная, её читают многие CLI-утилиты, не только Go. Если у вас уже есть SOCKS5-туннель (например, через SSH: ssh -D 1080 user@remote-host), можно пустить через него весь трафик go get без дополнительных настроек на сервере.
Для тестирования сборки из разных регионов (например, чтобы проверить, как ведёт себя пайплайн CI при запросе к региональному зеркалу пакетов или как реагирует внешний сервис на запросы из конкретной страны) нередко нужен канал с реальным IP-адресом, похожим на обычного пользователя, а не на дата-центр. В таких случаях выбирают резидентные прокси — они реже попадают под автоматические ограничения на стороне серверов раздачи модулей или приватных реестров пакетов.
Проверить, что прокси реально используется Go, можно простой командой с подробным выводом:
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
Флаг -x печатает каждую выполняемую команду, включая сетевые запросы, что помогает понять, реально ли go get идёт через прокси или игнорирует переменные окружения (это случается, если переменные экспортированы в другой сессии терминала или не прокинуты в подпроцесс).
Прокси в CI/CD и Docker
В CI-раннерах (GitHub Actions, GitLab CI, Jenkins) переменные окружения нужно прокидывать явно через настройки job, а не полагаться на локальный .bashrc, который в контейнере не читается.
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 (многоэтапная сборка):
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 .
Аргументы сборки передаются при вызове 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 .
Если сборка идёт параллельно на нескольких раннерах и нужно избежать бана по IP со стороны зеркала модулей из-за большого количества одновременных запросов (бывает с self-hosted Athens-прокси под высокой нагрузкой), полезно развести исходящие запросы через ротацию IP. Для равномерного распределения нагрузки и исключения rate-limit со стороны прокси-сервера зеркала модулей часто используют прокси дата-центров — они обеспечивают низкую задержку, что важно для CI, где каждая лишняя секунда умножается на число джобов.
Частые ошибки и их решения
| Ошибка | Причина | Решение |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org недоступен из сети | Сменить GOPROXY на зеркало или настроить HTTP_PROXY |
410 Gone |
Приватный модуль недоступен публичному прокси | Настроить GOPRIVATE для нужного пути модуля |
checksum mismatch |
GOSUMDB пытается проверить приватный модуль | Отключить через GONOSUMDB или GOSUMDB=off |
x509: certificate signed by unknown authority |
Корпоративный прокси подменяет TLS-сертификат (MITM) | Добавить корневой сертификат компании в системное хранилище |
repository not found |
Нет токена доступа для приватного git-репозитория | Настроить git config url.insteadOf с токеном |
| Переменные прокси игнорируются | Экспорт сделан в другой оболочке/сессии | Проверить через env | grep PROXY в той же сессии, где запускается go |
Отдельно стоит сказать про MITM-прокси (корпоративные Squid/Zscaler с подменой сертификатов): если такой прокси перехватывает HTTPS-трафик для анализа, Go-клиент не доверяет его самоподписанному сертификату, и это приводит к ошибке x509. Решение — экспортировать корневой сертификат компании в формате PEM и прописать его в переменную:
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
Эта переменная читается Go-рантаймом при проверке TLS-цепочки и позволяет работать через корпоративный MITM-прокси без отключения проверки сертификатов целиком (чего делать не стоит из соображений безопасности).
Заключение
Если Go-модули не скачиваются, в 90% случаев хватает трёх шагов: задать рабочий GOPROXY (публичное зеркало вместо заблокированного proxy.golang.org), добавить GOPRIVATE для внутренних репозиториев и прописать HTTP_PROXY/HTTPS_PROXY, если сеть выходит наружу только через корпоративный прокси. Для CI/CD эти переменные нужно передавать явно через переменные окружения job или build-аргументы Docker, а не полагаться на локальные конфиги разработчика.
Если причина сбоев — геоблокировка зеркала модулей или rate-limit со стороны прокси-сервера при параллельной сборке в CI, стоит пустить исходящий трафик через стабильный внешний канал. Для таких задач хорошо подходят прокси дата-центров — низкая задержка и предсказуемая пропускная способность критичны при массовой загрузке зависимостей. А если нужно эмулировать обычный пользовательский трафик при тестировании доступности внешних сервисов из разных регионов, подойдут резидентные прокси — они реже вызывают подозрения у систем защиты на стороне серверов раздачи пакетов.