← ブログに戻る

Android StudioとGradleでプロキシを設定する方法:gradle.propertiesとSDKマネージャー

プロキシをgradle.propertiesに正しく記述し、SDKマネージャーとAndroid Studioを設定し、Gradleの最も一般的な同期エラーを解決する方法を解説します。

📅2026年11月13日

Android StudioがGradle同期の段階で「フリーズ」し、SDK Managerがコンポーネントを読み込まず、Maven Centralから依存関係がダウンロードされない場合、80%のケースで問題はコードではなくネットワーク環境にあります。企業のファイアウォール、VPN、リポジトリのIPブロック、または単にインターネットへの直接アクセスがないことが原因です。これらは、IDE、Gradle、SDK Managerの3つのレベルでプロキシを正しく設定することで解決できます。プロキシを正しく設定し、余分な同期エラーを避ける方法を見ていきましょう。

Android開発者がプロキシを必要とする理由

Android Studioと組み合わせてプロキシを使用するシナリオは主にいくつかあります。最初のシナリオは、企業ネットワークで直接インターネットにアクセスできない場合で、すべてのトラフィック(google()、mavenCentral()、dl.google.comへのリクエストを含む)が企業のプロキシサーバーを経由する必要があります。第二のシナリオは地域制限の回避です。特定の国からは直接アクセスできないSDKコンポーネント、Google Play ServicesのAPI、またはサードパーティのリポジトリがあり、開発者はトラフィックを他の地理的位置のIPを経由してルーティングする必要があります。

第三のシナリオは、アプリケーションの地理依存機能のテストです。アプリがユーザーの国に応じて異なるコンテンツ、価格、または広告を表示する場合、QAエンジニアや開発者はリリースを待たずにビルドとデバッグの段階で必要な地域からのリクエストをエミュレートする必要があります。第四のシナリオは、特定のサービスへのアクセスが制限されているデータセンターに物理的に配置されたCI/CDランナーとの作業であり、プロキシは必要なリポジトリやAPIに「アクセスする」唯一の方法になります。

これらのすべてのケースでの論理は同じです。Gradle、SDK Manager、そしてIDE自体は、プロキシサーバーのアドレス、ポート、必要に応じて認証情報を知っている必要があります。そうでなければ、プロジェクトの同期はタイムアウトや接続エラーで失敗します。

開発に適したプロキシの種類

開発とテストでは、匿名性よりも接続の安定性と長時間のダウンロード中の切断率の低さが重要です(例えば、Android SDK Platform Toolsは数百メガバイトのサイズがあります)。以下は、Android開発者のタスクに関連するプロキシの種類の比較です。

プロキシの種類 使用するタイミング 特徴
データセンターのプロキシ SDKのダウンロード、Gradleの同期、CI/CD 高速、低価格、大きなダウンロードに安定
レジデンシャルプロキシ 地理依存のAPIとコンテンツのテスト 実際のユーザーのIP、サービスによるブロックが少ない
モバイルプロキシ 特定の国からのモバイルAPIとプッシュ通知のテスト 通信事業者のIP、実際のモバイルトラフィックに非常に近い

Gradleのクリーンな同期と依存関係のダウンロードには、データセンターのプロキシを使用するのが理にかなっています。これにより、余分な遅延なしに安定した高速が得られます。アプリのバックエンドが他の国のユーザーにどのように応答するかを確認する必要がある場合は、レジデンシャルまたはモバイルIPがより適しています。

gradle.propertiesでのプロキシ設定

gradle.propertiesファイルは、GradleがHTTPおよびHTTPS接続のためのプロキシ設定を探す主な場所です。このファイルはプロジェクトのルートに置くことができ(そのプロジェクトにのみ適用)、またはグローバルディレクトリ~/.gradle/gradle.propertiesに置くことができ(マシン上のすべてのプロジェクトに適用されます)。プロキシを通じて常に動作させるには、後者のオプションをお勧めします。

# ~/.gradle/gradle.properties

systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

# オプション — プロキシを経由せずに直接行く例外
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp

ファイルを保存した後は、必ずFile → Sync Project with Gradle Filesをクリックするか、ツールバーの「象」アイコンをクリックしてください。IDEが変更を自動的に認識しない場合は、Android Studioを再起動してください。時々、プロキシ設定のキャッシュはGradle Daemonプロセスの再起動まで保持されます。

重要な点: systemProp.*パラメータは、Gradleが実行されるJVMレベルでのみ機能します。したがって、依存関係のダウンロードだけでなく、ビルドスクリプト内のすべてのネットワークリクエストにも影響します(たとえば、外部APIを呼び出すカスタムGradleタスクがある場合)。

Android Studioでのプロキシ設定

Gradleの他に、IDEには独自のネットワーク設定があります。これはプラグイン、IDEの更新、ライセンスの確認、Googleからのヒントなどの機能に必要です。これらを開くには、File → Settings → Appearance & Behavior → System Settings → HTTP Proxy(macOSではAndroid Studio → Preferences)を選択します。

開いたウィンドウでManual proxy configurationを選択し、ホストとポートを指定します。必要に応じてProxy authenticationをチェックし、ログインとパスワードを入力します。同じ場所に便利なCheck connectionボタンがあります。テスト用のURL(例: https://dl.google.com)を入力し、接続が正しく行われることを確認してから、完全なプロジェクトの同期を開始してください。

違いを理解することが重要です

設定のHTTP ProxyはIDE自体に影響を与え(プラグイン、更新)、gradle.propertiesのパラメータはGradleビルドプロセスに影響を与えます。これは2つの独立したメカニズムであり、プロキシの背後で完全に機能させるには通常、両方を設定する必要があります。

SDK Manager用のプロキシ

SDK Managerは、Androidプラットフォーム、ビルドツール、エミュレーター、システムイメージをダウンロードするための独立したコンポーネントです。独自のプロキシ設定があり、歴史的にIDEの同じシステム設定を通じて設定されますが、スタンドアロンのsdkmanager(コマンドラインからのCLIユーティリティ)を使用する場合は、パラメータをJVMフラグを介して明示的に渡す必要があります。

sdkmanager --proxy=http \
  --proxy_host=proxy.example.com \
  --proxy_port=8080 \
  --list

sdkmanagerがスクリプトを介して起動される場合は、実行ファイルが読み取るJAVA_OPTS環境変数にプロキシを直接記述できます。

export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

よくあるエラーは、Android Studioでプロキシを設定したが、sdkmanagerやavdmanagerのようなスタンドアロンユーティリティを忘れてしまうことです。これらは別のJavaプロセスとして実行され、IDEの設定を自動的に継承しません。

gradlew用のプロキシと環境変数

IDEをバイパスしてターミナルから./gradlewラッパーを介してプロジェクトをビルドする場合(たとえば、CI/CDや単に習慣で)、プロキシをgradle.propertiesを変更せずにコマンドに直接渡すことができます。

./gradlew build \
  -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
  -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080

常に使用する場合は、シェルプロファイル(Linux/macOSの.bashrc、.zshrcまたはWindowsの環境変数)でGRADLE_OPTS環境変数を設定する方が便利です。

export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

これは、GitHub Actions、GitLab CI、JenkinsなどのCIランナーで特に便利です。ここでは、環境変数がジョブレベルで一度設定され、以降のすべてのビルドステップで自動的に取得され、プロジェクトファイルを編集する必要がありません。

一般的な同期エラーとその解決策

プロキシ設定中に開発者が直面する最も一般的なエラーと、それを解決するための具体的な手順を見ていきましょう。

エラー 原因 解決策
接続がタイムアウトしました プロキシが指定されていないか、利用できません gradle.propertiesのhost/portを確認し、curlでプロキシの可用性をテストしてください
407 Proxy Authentication Required ログイン/パスワードが渡されていない systemProp.http.proxyUserとsystemProp.http.proxyPasswordを追加してください
ホストを解決できませんでした DNS解決がプロキシを経由していない SOCKS5のリモートDNS用にsocksProxyHostをhttpの代わりに使用してください
'https://dl.google.com/...'を取得できませんでした Gradle設定が指定されているが、IDEでは指定されていない(またはその逆) 両方の場所で設定を同期してください: Settings → HTTP Proxyとgradle.properties
SSLハンドシェイクに失敗しました プロキシがSSLを傍受しています(企業のMITM) プロキシのルート証明書をJDKのcacertsにインポートしてください

特定のMavenアーティファクト(例えば、androidx.*ライブラリ)をダウンロードする際にエラーが発生する場合、Gradleの詳細ログを一時的に有効にすることが役立ちます。コマンド./gradlew build --infoを実行すると、接続が切断されるリクエストとサーバーが返すレスポンスコードが表示されます。

認証付きプロキシ: ログインとパスワード

プロキシが認証を必要とする場合(これは有料プロキシサービスや企業のゲートウェイでは一般的な状況です)、gradle.propertiesにさらに2行を追加する必要があります。

systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword

プロジェクトのgradle.propertiesにプロキシのパスワードを平文で保存することは、バージョン管理システムに含まれるため悪い習慣です。Gitにコミットされないユーザーのホームディレクトリにグローバルファイルを使用するか、CI/CDの段階で環境変数を介してパスワードを渡して、秘密がリポジトリに漏れないようにしてください。

IPのローテーションが必要なシナリオ(例えば、異なるアドレスからのAPI制限のテスト)では、アドレスのプールと単一のログインを備えたプロキシサービスを利用する方が便利です。これにより、プロバイダー側でローテーションが設定され、gradle.propertiesではセッションのポートのみが変更され、プロジェクト全体の設定を再記述する必要がありません。

診断チェックリスト

すべての設定を行った後でも同期が失敗する場合は、次の項目を順に確認してください。

  • プロキシの可用性を直接確認するコマンドcurl -x http://proxy.example.com:8080 https://dl.google.comを実行してください
  • Settings → HTTP Proxyとgradle.propertiesの両方に設定が記載されていることを確認してください
  • Gradleキャッシュをクリアしてください: ./gradlew --stopを実行し、.gradle/cachesフォルダを削除してください
  • ファイル内にホスト/ポートの値の周りに余分なスペースや引用符がないことを確認してください
  • SOCKS5を使用している場合は、http.proxyHostの代わりにsocksProxyHost/socksProxyPortを指定してください
  • 企業のMITMプロキシの場合、証明書をJDKの信頼された証明書ストアにインポートしてください(keytool -import)
  • propertiesファイルに変更を加えた後は、Android StudioとGradle Daemonを再起動してください

結論

Android開発におけるプロキシ設定は、Android Studioのシステム設定、ビルドプロセスのためのgradle.propertiesのsystemPropパラメータ、sdkmanagerのようなスタンドアロンユーティリティのための独自の設定の3つのレベルで行われます。ほとんどの同期エラーは、これらのレベルのいずれかが設定されているが、他のレベルが忘れられている場合、または認証が必要なプロキシで認証が欠如していることから発生します。

依存関係やSDKコンポーネントを安定してダウンロードするだけが目的であれば、データセンターのプロキシが最適です。これらは高速で、大きなダウンロード時に余分な遅延を生じさせません。特定の国のユーザーやモバイルオペレーターに対するアプリの動作をテストする必要がある場合は、レジデンシャルプロキシやモバイルIPを検討してください。これらは異なる地域でのサービスの動作をよりリアルに反映します。