← Kembali ke blog

Go-modul tidak diunduh: pengaturan GOPROXY, GOPRIVATE, dan HTTP-proxy untuk go get

Panduan langkah demi langkah untuk mengatur GOPROXY, GOPRIVATE, dan proxy jaringan untuk go get — bagi mereka yang tidak dapat mengunduh modul Go di balik firewall perusahaan atau dalam CI/CD.

📅20 November 2026

Perintah go get terhenti, gagal dengan timeout atau menghasilkan dial tcp: i/o timeout — situasi yang akrab bagi pengembang di balik firewall perusahaan, dalam jaringan tertutup, atau saat bekerja dengan repositori GitLab/GitHub pribadi. Dalam 90% kasus, penyebabnya adalah pengaturan GOPROXY yang salah, tidak adanya GOPRIVATE, atau pemblokiran akses langsung ke proxy.golang.org oleh firewall. Mari kita bahas cara memperbaikinya dengan benar.

Mengapa modul Go tidak diunduh

Sejak versi Go 1.13, sistem modul secara default mengakses proxy publik proxy.golang.org dan server pemeriksaan checksum sum.golang.org. Jika kedua layanan diblokir di tingkat jaringan (ini umum terjadi di Rusia, Cina, dan segmen perusahaan dengan batasan), perintah go build atau go mod tidy akan terhenti hingga timeout, dan kemudian menghasilkan kesalahan:

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

Ada tiga skenario umum yang menyebabkan pengunduhan modul gagal:

  • Pemblokiran jaringan — penyedia atau firewall perusahaan memotong akses ke infrastruktur Google, di mana proxy.golang.org dan sum.golang.org berada.
  • Repositori pribadi — modul terletak di GitLab/Bitbucket internal, dan GOPROXY publik secara fisik tidak dapat mengaksesnya, dan juga mencoba memeriksa checksum-nya di sum.golang.org, meskipun seharusnya tidak.
  • Proxy server di jaringan tanpa variabel lingkungan yang diatur — lalu lintas keluar hanya melalui proxy HTTP/SOCKS5, tetapi Go tidak tahu tentang hal ini, karena go get menggunakan klien net/http standar, yang membaca variabel lingkungan, bukan pengaturan proxy sistem dari browser.

Selanjutnya, kita akan membahas setiap kasus dengan perintah dan file konfigurasi yang spesifik.

Apa itu GOPROXY dan bagaimana cara kerjanya

GOPROXY adalah variabel lingkungan yang menunjukkan kepada alat Go dari mana mengunduh modul. Secara default (mulai dari Go 1.14), nilainya adalah:

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

Nilai yang dipisahkan dengan koma adalah daftar sumber yang akan dicoba Go secara berurutan. direct berarti "unduh langsung dari VCS (git, svn, hg), jika proxy mengembalikan 404 atau 410". Jika proxy tidak tersedia secara fisik (timeout, bukan 404), Go tidak beralih ke sumber berikutnya — ia hanya terhenti atau gagal karena timeout. Ini adalah poin kunci yang banyak orang tidak pahami: mekanisme fallback hanya berfungsi untuk "modul tidak ditemukan", bukan untuk "jaringan tidak tersedia".

Selain proxy.golang.org, ada cermin publik yang dapat digunakan sebagai alternatif:

Server GOPROXY URL Fitur
Google resmi proxy.golang.org Sering diblokir di jaringan tertutup
goproxy.cn goproxy.cn Cermin dari komunitas Cina, stabil tersedia
Astra (goproxy.io) goproxy.io Cermin global alternatif
Athens (self-hosted) server sendiri Kontrol penuh, cocok untuk cache modul perusahaan

Pengaturan GOPROXY: konfigurasi yang berfungsi

Variabel lingkungan Go dapat diatur sementara (untuk sesi) atau secara permanen melalui go env -w, yang menyimpan nilai dalam file konfigurasi Go (biasanya ~/.config/go/env di Linux/macOS dan %APPDATA%\go\env di Windows).

Pengaturan permanen (disarankan):

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

Periksa nilai saat ini:

go env GOPROXY

Jika perlu beberapa cermin dengan cadangan:

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

Nuansa penting: jika proxy pertama dalam daftar merespons dengan timeout, bukan kesalahan HTTP, beralih ke sumber berikutnya bisa memakan waktu hingga satu menit untuk setiap modul — ini membunuh kecepatan build di CI. Oleh karena itu, jika jaringan secara fisik tidak dapat mencapai proxy pertama, lebih baik segera menghapusnya dari daftar atau mengatur akses jaringan melalui proxy server (lihat bagian di bawah), daripada mengandalkan fallback.

Jika ingin sepenuhnya menonaktifkan akses ke proxy eksternal dan hanya bekerja dari cache lokal atau langsung dari VCS:

go env -w GOPROXY=direct

GOPRIVATE, GONOSUMCHECK, dan GOSUMDB

Ketika modul terletak di repositori Git internal (GitLab perusahaan, Bitbucket Server, Gitea yang dihosting sendiri), Go tetap akan mencoba memeriksanya melalui GOPROXY publik dan mencocokkan hash melalui GOSUMDB — dan ini tidak mungkin, karena kode pribadi tidak dipublikasikan ke luar. Hasilnya adalah kesalahan 410 Gone atau verifying module: checksum mismatch.

Solusinya adalah variabel GOPRIVATE, yang memberi tahu Go: "jalur modul ini adalah pribadi, jangan cari di proxy publik dan jangan periksa checksum".

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

GOPRIVATE secara otomatis mengatur dua flag sekaligus: GONOSUMCHECK (menonaktifkan pemeriksaan hash melalui GOSUMDB) dan GOPROXY=direct untuk jalur yang ditentukan. Namun, jika perlu pengaturan yang lebih halus, dapat diatur secara terpisah:

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

Untuk repositori pribadi di GitHub, perlu juga mengatur git untuk menggunakan token alih-alih SSH saat mengkloning melalui HTTPS, karena alat Go menggunakan git di belakang layar:

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

Perintah ini menggantikan semua permintaan HTTPS ke github.com dengan permintaan yang menyertakan token dalam URL, yang memungkinkan klien Go mengunduh modul pribadi tanpa memasukkan login/kata sandi secara interaktif.

Proxy HTTP/HTTPS untuk go get

Jika kantor atau server berada di belakang proxy HTTP perusahaan (misalnya, Squid), Go tidak akan mengetahuinya secara otomatis — ia hanya membaca variabel lingkungan HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY, yang standar untuk klien 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

Untuk tidak menulis ini setiap kali, tambahkan baris ke ~/.bashrc, ~/.zshrc, atau ~/.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"

Untuk penyimpanan permanen di Windows, gunakan setx:

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

Penting: NO_PROXY harus mencakup domain internal (GitLab internal, server Athens lokal), jika tidak, permintaan ke mereka juga akan melalui proxy eksternal dan akan gagal dengan kesalahan akses.

Jika GOPROXY publik tidak tersedia bukan karena firewall internal, tetapi karena pemblokiran geografis di wilayah tertentu — situasi yang dihadapi tim yang servernya tersebar di berbagai negara — alih-alih menggunakan proxy HTTP perusahaan, Anda dapat membuat terowongan keluar melalui server proxy eksternal dengan geolokasi yang diinginkan. Untuk skenario semacam itu, proxy data center proxy data center sangat cocok — mereka memberikan saluran cepat yang stabil dan latensi yang dapat diprediksi, yang sangat penting saat mengunduh dependensi secara massal dalam pipeline CI.

Proxy SOCKS5 dan cara menghindari pemblokiran

Variabel HTTP_PROXY/HTTPS_PROXY tidak hanya mendukung proxy HTTP(S), tetapi juga SOCKS5 — mulai dari Go 1.10+ pustaka standar dapat bekerja melalui skema 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

Variabel ALL_PROXY adalah universal, dibaca oleh banyak utilitas CLI, tidak hanya Go. Jika Anda sudah memiliki terowongan SOCKS5 (misalnya, melalui SSH: ssh -D 1080 user@remote-host), Anda dapat mengalirkan semua lalu lintas go get melalui itu tanpa pengaturan tambahan di server.

Untuk menguji build dari berbagai wilayah (misalnya, untuk memeriksa bagaimana pipeline CI berperilaku saat meminta cermin paket regional atau bagaimana layanan eksternal bereaksi terhadap permintaan dari negara tertentu) sering kali diperlukan saluran dengan alamat IP nyata yang mirip dengan pengguna biasa, bukan dari data center. Dalam kasus seperti itu, proxy residensial dipilih — mereka lebih jarang terkena batasan otomatis di sisi server distribusi modul atau registri paket pribadi.

Untuk memeriksa bahwa proxy benar-benar digunakan oleh Go, Anda dapat menggunakan perintah sederhana dengan output yang terperinci:

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

Flag -x mencetak setiap perintah yang dieksekusi, termasuk permintaan jaringan, yang membantu memahami apakah go get benar-benar melalui proxy atau mengabaikan variabel lingkungan (ini terjadi jika variabel diekspor di sesi terminal lain atau tidak diteruskan ke subprocess).

Proxy dalam CI/CD dan Docker

Dalam runner CI (GitHub Actions, GitLab CI, Jenkins), variabel lingkungan harus diteruskan secara eksplisit melalui pengaturan pekerjaan, dan tidak mengandalkan .bashrc lokal, yang tidak dibaca di dalam kontainer.

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 (build multi-stage):

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 .

Argumen build diteruskan saat memanggil 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 .

Jika build berjalan secara paralel di beberapa runner dan perlu menghindari pemblokiran IP dari cermin modul karena banyaknya permintaan simultan (sering terjadi dengan proxy Athens yang dihosting sendiri di bawah beban tinggi), berguna untuk mendistribusikan permintaan keluar melalui rotasi IP. Untuk distribusi beban yang merata dan menghindari batasan laju dari server proxy cermin modul, sering digunakan proxy data center — mereka menyediakan latensi rendah, yang penting untuk CI, di mana setiap detik tambahan dikalikan dengan jumlah pekerjaan.

Kesalahan umum dan solusinya

Kesalahan Penyebab Solusi
dial tcp: i/o timeout proxy.golang.org tidak tersedia dari jaringan Ganti GOPROXY dengan cermin atau atur HTTP_PROXY
410 Gone Modul pribadi tidak tersedia untuk proxy publik Atur GOPRIVATE untuk jalur modul yang diperlukan
checksum mismatch GOSUMDB mencoba memeriksa modul pribadi Nonaktifkan melalui GONOSUMDB atau GOSUMDB=off
x509: certificate signed by unknown authority Proxy perusahaan mengganti sertifikat TLS (MITM) Tambahkan sertifikat root perusahaan ke penyimpanan sistem
repository not found Tidak ada token akses untuk repositori git pribadi Atur git config url.insteadOf dengan token
Variabel proxy diabaikan Ekspor dilakukan di shell/sesi lain Periksa melalui env | grep PROXY di sesi yang sama di mana go dijalankan

Secara terpisah, perlu dibahas tentang proxy MITM (Squid/Zscaler perusahaan dengan penggantian sertifikat): jika proxy semacam itu menangkap lalu lintas HTTPS untuk analisis, klien Go tidak mempercayai sertifikat self-signed-nya, dan ini menyebabkan kesalahan x509. Solusinya adalah mengekspor sertifikat root perusahaan dalam format PEM dan menetapkannya dalam variabel:

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

Variabel ini dibaca oleh runtime Go saat memeriksa rantai TLS dan memungkinkan bekerja melalui proxy MITM perusahaan tanpa menonaktifkan pemeriksaan sertifikat sepenuhnya (yang seharusnya tidak dilakukan demi keamanan).

Kesimpulan

Jika modul Go tidak diunduh, dalam 90% kasus cukup dengan tiga langkah: atur GOPROXY yang berfungsi (cermin publik sebagai pengganti proxy.golang.org yang diblokir), tambahkan GOPRIVATE untuk repositori internal, dan tetapkan HTTP_PROXY/HTTPS_PROXY jika jaringan keluar hanya melalui proxy perusahaan. Untuk CI/CD, variabel ini perlu diteruskan secara eksplisit melalui variabel lingkungan pekerjaan atau argumen build Docker, dan tidak mengandalkan konfigurasi lokal pengembang.

Jika penyebab kegagalan adalah pemblokiran geografis pada cermin modul atau batasan laju dari server proxy saat build paralel di CI, sebaiknya alirkan lalu lintas keluar melalui saluran eksternal yang stabil. Untuk tugas semacam itu, proxy data center proxy data center sangat cocok — latensi rendah dan bandwidth yang dapat diprediksi sangat penting saat mengunduh dependensi secara massal. Dan jika perlu mensimulasikan lalu lintas pengguna biasa saat menguji aksesibilitas layanan eksternal dari berbagai wilayah, proxy residensial proxy residensial cocok — mereka lebih jarang menimbulkan kecurigaan di sisi server distribusi paket.