← 블로그로 돌아가기

Go 모듈 다운로드 실패: go get을 위한 GOPROXY, GOPRIVATE 및 HTTP 프록시 설정 방법

GOPROXY, GOPRIVATE 및 네트워크 프록시 설정에 대한 단계별 안내 — 기업 방화벽이나 CI/CD에서 Go 모듈을 다운로드할 수 없는 사용자용.

📅2026년 11월 20일

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

모듈 다운로드가 실패하는 세 가지 일반적인 시나리오가 있습니다:

  • 네트워크 차단 — 제공업체 또는 기업 방화벽이 proxy.golang.org 및 sum.golang.org가 호스팅되는 Google 인프라에 대한 접근을 차단합니다.
  • 개인 리포지토리 — 모듈이 내부 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는 "프록시가 404 또는 410을 반환하면 VCS(깃, svn, hg)에서 직접 다운로드"를 의미합니다. 만약 프록시가 물리적으로 접근할 수 없다면(타임아웃, 404가 아님), Go는 다음 출처로 넘어가지 않고 그냥 멈추거나 타임아웃 오류를 발생시킵니다. 이는 많은 사람들이 이해하지 못하는 중요한 점입니다: fallback 메커니즘은 "모듈을 찾을 수 없음"에 대해서만 작동하며 "네트워크에 접근할 수 없음"에 대해서는 작동하지 않습니다.

proxy.golang.org 외에도 대안으로 사용할 수 있는 공개 미러가 있습니다:

GOPROXY 서버 URL 특징
구글 공식 proxy.golang.org 종종 폐쇄된 네트워크에서 차단됨
goproxy.cn goproxy.cn 중국 커뮤니티의 미러, 안정적으로 접근 가능
Astra (goproxy.io) goproxy.io 대체 글로벌 미러
Athens (자체 호스팅) 자체 서버 완전한 제어, 기업 모듈 캐시에 적합

GOPROXY 설정: 작동하는 구성

Go 환경 변수는 임시로(세션 동안) 또는 go env -w를 통해 영구적으로 설정할 수 있으며, 이는 Go 구성 파일에 값을 저장합니다(일반적으로 Linux/macOS에서는 ~/.config/go/env, Windows에서는 %APPDATA%\go\env).

영구 설정(권장):

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

중요한 점: 목록의 첫 번째 프록시가 타임아웃으로 응답하면, 다음 출처로 넘어가는 데 각 모듈마다 최대 1분이 걸릴 수 있습니다 — 이는 CI에서 빌드 속도를 저하시킵니다. 따라서 네트워크가 첫 번째 프록시까지 물리적으로 도달할 수 없다면, 목록에서 제거하거나 프록시 서버를 통해 네트워크 접근을 설정하는 것이 좋습니다(아래 섹션 참조).

외부 프록시 접근을 완전히 비활성화하고 로컬 캐시 또는 VCS에서 직접 작업하고 싶다면:

go env -w GOPROXY=direct

GOPRIVATE, GONOSUMCHECK 및 GOSUMDB

모듈이 내부 Git 리포지토리(기업 GitLab, Bitbucket Server, 자체 호스팅 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의 개인 리포지토리의 경우, HTTPS를 통해 클론할 때 SSH 대신 토큰을 사용하도록 git을 추가로 설정해야 합니다. Go 도구는 내부적으로 git을 사용하기 때문입니다:

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

이 명령어는 github.com에 대한 모든 HTTPS 요청을 URL에 토큰을 포함한 요청으로 대체하여 Go 클라이언트가 개인 모듈을 로그인/비밀번호 입력 없이 다운로드할 수 있도록 합니다.

go get을 위한 HTTP/HTTPS 프록시

사무실이나 서버가 기업 HTTP 프록시(예: Squid) 뒤에 있을 경우, Go는 이를 자동으로 인식하지 못합니다 — Go net/http 클라이언트에 표준으로 설정된 환경 변수 HTTP_PROXY, HTTPS_PROXY 및 NO_PROXY만 읽습니다.

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 유틸리티에서 읽습니다. 이미 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)에서는 환경 변수를 작업 설정을 통해 명시적으로 전달해야 하며, 로컬 .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 차단을 피해야 하는 경우(이는 고부하 상태의 자체 호스팅 Athens 프록시에서 발생할 수 있음), 아웃바운드 요청을 IP 회전을 통해 분산하는 것이 유용합니다. 부하를 고르게 분산하고 미러 프록시 서버의 속도 제한을 피하기 위해 데이터 센터 프록시를 자주 사용합니다 — 이들은 낮은 지연을 보장하여 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 설정
프록시 변수가 무시됨 내보내기가 다른 셸/세션에서 이루어짐 go가 실행되는 동일한 세션에서 env | grep PROXY를 통해 확인

MITM 프록시(기업 Squid/Zscaler가 인증서를 변조하는 경우)에 대해 별도로 언급할 필요가 있습니다: 이러한 프록시가 HTTPS 트래픽을 가로채어 분석하는 경우, Go 클라이언트는 자가 서명된 인증서를 신뢰하지 않으며, 이는 x509 오류로 이어집니다. 해결책은 PEM 형식의 기업 루트 인증서를 내보내고 이를 변수에 설정하는 것입니다:

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

이 변수는 TLS 체인을 확인할 때 Go 런타임에 의해 읽히며, 기업 MITM 프록시를 통해 인증서 검증을 전체적으로 비활성화하지 않고도 작업할 수 있게 해줍니다(보안상의 이유로 그렇게 해서는 안 됩니다).

결론

Go 모듈이 다운로드되지 않는 경우, 90%의 경우 세 가지 단계로 해결할 수 있습니다: 작동하는 GOPROXY 설정(차단된 proxy.golang.org 대신 공개 미러 사용), 내부 리포지토리에 대한 GOPRIVATE 추가 및 네트워크가 기업 프록시를 통해서만 외부로 나가는 경우 HTTP_PROXY/HTTPS_PROXY 설정. CI/CD의 경우 이러한 변수는 작업 또는 Docker 빌드 인자에서 명시적으로 전달해야 하며, 개발자의 로컬 구성에 의존해서는 안 됩니다.

오류의 원인이 모듈 미러의 지리적 차단이나 CI에서 병렬 빌드 시 프록시 서버의 속도 제한인 경우, 안정적인 외부 채널을 통해 아웃바운드 트래픽을 보내는 것이 좋습니다. 이러한 작업에는 데이터 센터 프록시가 적합합니다 — 낮은 지연과 예측 가능한 대역폭은 의존성을 대량으로 다운로드할 때 중요합니다. 외부 서비스의 접근 가능성을 테스트할 때 다양한 지역에서 일반 사용자 트래픽을 에뮬레이션해야 하는 경우, 주거용 프록시가 적합합니다 — 이들은 패키지 배포 서버의 보호 시스템에서 의심을 덜 받습니다.