← ブログに戻る

Goモジュールがダウンロードできない: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

モジュールのダウンロードが失敗する典型的なシナリオは三つあります:

  • ネットワークブロック — プロバイダーまたは企業ファイアウォールが 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 は「プロキシが 404 または 410 を返した場合、VCS(git、svn、hg)から直接ダウンロードする」という意味です。プロキシが物理的に利用できない場合(タイムアウト、404 ではなく)、Go は次のソースに進むことはなく、単にハングするか、タイムアウトで失敗します。これは多くの人が理解していない重要なポイントです: フォールバックメカニズムは「モジュールが見つからない」場合にのみ機能し、「ネットワークが利用できない」場合には機能しません。

proxy.golang.org の他にも、代替として使用できる公開ミラーがあります:

GOPROXY サーバー URL 特徴
Google 公式 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 エラーが発生します。

解決策は、Go に「これらのモジュールパスはプライベートであり、公開プロキシにアクセスせず、チェックサムを確認しないでください」と指示する環境変数 GOPRIVATE です。

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 はこれを自動的に認識しません — それは 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 ツールがこれを読み取ります。すでに 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 での並行ビルド時のプロキシサーバーによるレート制限である場合、安定した外部チャネルを介して出力トラフィックを流すことを検討してください。このようなタスクには、データセンターのプロキシ が適しています — 低遅延と予測可能な帯域幅は、依存関係の大量ダウンロード時に重要です。また、異なる地域から外部サービスの可用性をテストする際に通常のユーザートラフィックをエミュレートする必要がある場合は、レジデンシャルプロキシ が適しています — これにより、パッケージ配布サーバーの保護システムに疑念を抱かれることが少なくなります。