← Назад к блогу

Go-модули не скачиваются: настройка GOPROXY, GOPRIVATE и HTTP-прокси для go get

Пошаговая инструкция по настройке GOPROXY, GOPRIVATE и сетевого прокси для go get — для тех, у кого Go-модули не скачиваются за корпоративным файрволом или в CI/CD.

📅20 ноября 2026 г.

Команда 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, стоит пустить исходящий трафик через стабильный внешний канал. Для таких задач хорошо подходят прокси дата-центров — низкая задержка и предсказуемая пропускная способность критичны при массовой загрузке зависимостей. А если нужно эмулировать обычный пользовательский трафик при тестировании доступности внешних сервисов из разных регионов, подойдут резидентные прокси — они реже вызывают подозрения у систем защиты на стороне серверов раздачи пакетов.