Gradleとgradle.propertiesの基本知識

Gradleとgradle.propertiesの役割を理解する

GradleはJavaなどのJVMプロジェクトで利用できるビルド自動化ツールです。コンパイル、テスト実行、依存関係の取得、JARなどの成果物作成、リポジトリへの公開までを一括して自動化できます。Gradle自体がJavaコンパイラなのではなく、各種処理をタスクとして構成・実行する役割を担います。ビルド設定はGroovy DSL（build.gradle）またはKotlin DSL（build.gradle.kts）で記述します。（出典：Gradle「Gradle Build Tool Features」）

gradle.propertiesは、Gradleの動作を制御するプロパティを記述する設定ファイルです。プロジェクトルートとGradleホーム（~/.gradle/）の2箇所に配置でき、両方ある場合は両方の設定が読み込まれます。プロキシ設定やデーモンのJVMメモリ、ビルドキャッシュ有効化など、ビルド環境に依存する設定をこのファイルに記述します。プロジェクト固有の設定はプロジェクトのgradle.propertiesに、ユーザー固有の設定や機密情報はユーザーホーム側に置くのが安全な運用です。

Gradle Wrapperとビルド実行の基本

Gradleを実行するにはJDK 17以上が必要です。現行バージョンはJava 17〜26をサポートしていますが、JavaのバージョンとGradleのバージョンは別物です。たとえばJava 26でGradleを実行するにはGradle 9.4.0以降、Java 21なら8.5以降が必要です。古い記事にある「JDK 8でGradleを実行できる」という情報は現行版には当てはまりません。（出典：Gradle「Compatibility Matrix」）

Javaプロジェクトでは、Gradle本体を手動インストールするよりもGradle Wrapper（gradlew）の利用が公式推奨です。Wrapperを使うとプロジェクトごとにGradleバージョンを固定でき、開発者全員とCI環境で同じバージョンを使用できます。既存プロジェクトではgradlewの有無、gradle-wrapper.propertiesに記載されたバージョン、使用JDKバージョンをまず確認しましょう。（出典：Gradle「Gradle Wrapper Basics」）

ビルドライフサイクルとConfigurationフェーズの重要性

Gradleのビルドは3つのフェーズで構成されます。まずInitializationでsettings.gradleを評価しプロジェクトを特定、次にConfigurationでbuild.gradleを評価してタスクグラフを構築、最後にExecutionでタスクを実行します。かつてはExecutionが最長でしたが、プロジェクト規模が大きくなるにつれConfigurationフェーズがボトルネックになるケースが増えています。（出典：Gradle公式ブログ「Achieving Fast Inner Dev Loops with Gradle」）

この3フェーズ構造を理解すると、どの設定がどのフェーズに影響するかが見えてきます。gradle.propertiesのプロキシ設定は依存関係の取得（Executionフェーズ）に影響し、Configuration CacheはConfigurationフェーズをスキップする仕組みです。パフォーマンス最適化を効果的に行うには、まずビルドのどの段階で時間がかかっているかを把握することが重要です。

gradle.propertiesでプロキシを設定する方法

HTTP・HTTPSプロキシの基本設定

Gradleのプロキシ設定は標準のJVMシステムプロパティで行います。gradle.propertiesではsystemProp.プレフィックスを付けて記述します。HTTPプロキシの基本設定は次のとおりです。

  • systemProp.http.proxyHost：プロキシホスト名
  • systemProp.http.proxyPort：プロキシポート番号
  • systemProp.http.proxyUser：認証ユーザー名
  • systemProp.http.proxyPassword：認証パスワード
  • systemProp.http.nonProxyHosts：プロキシを経由しないホストを|区切りで指定

HTTPSプロキシはHTTPとは別の設定が必要です。http.をhttps.に置き換えたプロパティを同じように記述します。HTTPS接続でHTTPプロキシ設定だけを書いてもプロキシを経由しないため、両方の設定を忘れないようにしましょう。（出典：Gradle User Manual「Networking with Gradle」）

SOCKSプロキシとNTLM認証の設定

SOCKSプロキシを使用する場合は、HTTP/HTTPSとは別のプロパティを使用します。systemProp.socksProxyHostとsystemProp.socksProxyPortでホストとポートを指定し、認証情報はsystemProp.java.net.socks.usernameとsystemProp.java.net.socks.passwordで設定します。SOCKSプロキシはHTTP/HTTPSプロキシと組み合わせて使うことも可能です。

企業ネットワークなどでNTLM認証が必要なプロキシを利用する場合は、認証ドメインの指定が必要になることがあります。方法は2通りあり、http.proxyUserを「ドメイン名/ユーザー名」形式で設定するか、http.auth.ntlm.domainプロパティで認証ドメインを個別に指定します。NTLMはWindows環境特有の認証方式なので、それ以外の環境では通常必要ありません。

プロキシ設定の注意点と安全な運用

プロキシ設定にはパスワードが含まれるため、機密情報の取り扱いに注意が必要です。プロジェクトのgradle.propertiesにプロキシパスワードを記述すると、Gitなどのバージョン管理システムに平文でコミットされるリスクがあります。パスワードを含む設定はユーザーホームの~/.gradle/gradle.propertiesに置くのが安全側の運用です。チーム内でプロキシ設定を共有する必要がある場合は、ホスト名やポート番号のみをプロジェクト側に記載し、認証情報は各自のホームディレクトリで設定する方法が推奨されます。

また、nonProxyHostsで内部リポジトリやローカルホストをプロキシ対象から除外すると、ビルドの高速化と不要なプロキシ負荷の回避ができます。たとえば社内のMavenリポジトリにアクセスする際にプロキシを経由させない設定は、ビルドパフォーマンスの観点からも有効です。

Gradleのビルドパフォーマンスを左右する主要機能

Gradle Daemonの仕組みと設定

Gradle Daemonはビルドプロセスを常駐させ、次回以降のJVM起動コストを削減する仕組みです。Gradle 3.0以降デフォルトで有効になっており、特別な設定は不要ですが、パフォーマンス調整のために知っておくべきプロパティがあります。デーモンのアイドルタイムアウトはデフォルトで3時間です。ビルド後もデーモンがメモリを消費し続けるため、CI環境などではorg.gradle.daemon.idletimeoutで短く設定するとリソース節約になります。単位はミリ秒で、30分なら1800000と指定します。（出典：Gradle User Manual「Gradle Daemon」）

デーモンのJVMメモリはorg.gradle.jvmargsで設定します。たとえば-Xmx2048mと指定するとヒープサイズを2GBに拡張できます。Gradle公式はJVMメモリ不足がビルドパフォーマンス低下の一般的な原因と指摘しています。ガベージコレクションに時間がかかっている場合は、ヒープサイズの増加を検討しましょう。デーモンの状態はgradle --statusで確認できます。

増分コンパイルと依存関係の最適化

増分コンパイルは変更されたクラスのみを再コンパイルする機能で、Javaではデフォルトで有効です。再コンパイルの範囲をさらに小さくするには、apiとimplementationの使い分けが重要です。implementationで宣言した依存関係は下流のプロジェクトのcompileクラスパスに漏れないため、内部実装が変わってもapi依存のみ再コンパイルされます。大規模マルチプロジェクトで変更の波及を大幅に削減できます。

依存関係の解決もビルド時間に大きく影響します。Gradleはリポジトリを宣言順に検索するため、最も多くの依存関係をホストしているリポジトリを先頭に宣言すると検索回数が減ります。また、動的バージョン（2.+など）やスナップショットバージョンはリモートリポジトリへの問い合わせが発生するため、可能な限り固定バージョンを使うことが推奨されます。リポジトリ数も必要最小限に絞りましょう。（出典：Gradle User Manual「Improving the Performance of Gradle Builds」）

並列実行とテストの最適化

並列実行はorg.gradle.parallel=trueで有効にできます。ただし、Gradle公式はデカップリングされたプロジェクトでのみ使用すべきとしています。密結合なプロジェクトで有効にすると問題が発生し得るため、マルチプロジェクト構成が疎結合であることを確認してから設定してください。Configuration Cacheを有効にすると、--parallelフラグなしでもタスクが並列実行されます。

テストの並列実行もパフォーマンス改善に有効です。JUnitテストではmaxParallelForksでテストVMのフォーク数を設定できます。推奨値はCPUコア数の半分程度です。ただし、テストが独立していることが前提で、ファイルやDBを共有するテストでは並列実行できません。forkEveryで定期的にテストVMを再起動する設定はメモリリーク対策に有効ですが、小さい値に設定するとフォークのオーバーヘッドで逆に遅くなるので注意しましょう。

ビルドキャッシュとConfiguration Cacheで高速化する設定

Configuration Cacheの概要と有効化

Configuration CacheはConfigurationフェーズの結果をキャッシュし、次回以降のビルドでこのフェーズを丸ごとスキップする機能です。タスクの実行結果をキャッシュするBuild Cacheとは別物で、タスクグラフの構築コストを削減します。gradle.propertiesにorg.gradle.configuration-cache=trueと記述するだけで有効になります。Gradle 9.0以降「推奨実行モード」として位置づけられているため、新規プロジェクトでは積極的な導入が推奨されます。（出典：Gradle User Manual「Configuration Cache」）

キャッシュエントリはビルドスクリプトなどの設定入力が変わると自動的に無効化されます。未追跡の入力が変わった場合は.gradle/configuration-cacheディレクトリを削除して手動で無効化します。キャッシュエントリは24時間ごとに使用状況がチェックされ、7日間使われなければ自動削除されるため、ディスク領域の心配は比較的少なくて済みます。問題発生時はorg.gradle.configuration-cache.problems=warnで警告にフォールバックできます。

Build Cacheの仕組みとローカルキャッシュ

Build Cacheはタスクの出力をキャッシュし、同じ入力のタスク再実行を回避する機能です。コンパイル済みクラス、生成ソース、パッケージ化された成果物などがキャッシュ対象です。有効化はorg.gradle.caching=trueまたはコマンドラインで--build-cacheを指定します。ローカルビルドキャッシュはデフォルトで有効で、保存場所はGradleユーザーホーム内のcaches/build-cache-1です。Gradleが定期的にクリーニングするため、ディスク容量の管理も自動で行われます。（出典：Gradle User Manual「Build Cache」）

ローカルキャッシュの保存場所はsettings.gradleでプロジェクト固有のディレクトリに変更できます。CI環境ではクリーンビルドごとにキャッシュが消えるため、永続化したい場合は別ディレクトリに設定するとよいでしょう。ただし、ローカルキャッシュはあくまで同一マシン内での再利用が前提です。チーム全体でキャッシュを共有するにはリモートビルドキャッシュの設定が必要です。

リモートビルドキャッシュの構成と注意点

リモートビルドキャッシュはHTTP経由でキャッシュを共有する仕組みです。HttpBuildCacheでURLを指定して設定します。Gradle公式の推奨構成は、CIサーバーがクリーンビルドでリモートキャッシュを更新（push）し、開発者はそこから読み取り（pull）だけする形です。デフォルトではローカルキャッシュはpush有効、リモートキャッシュはpush無効なので、CI環境かどうかを環境変数で判定してpushプロパティを切り替える実装がよく使われます。

HTTPS接続では証明書がJavaランタイムのトラストストアに含まれている必要があります。isAllowUntrustedServer=trueで信頼要件を無効化できますが、セキュリティリスクがあるため一時的な措置としてのみ使用してください。ネットワークエラー発生時は送信が自動で最大3回リトライされ、それでも失敗するとリモートキャッシュはビルドの残りで無効化されます。オフライン環境では--offlineフラグでキャッシュからのみ依存関係を解決することも可能です。

要点：Configuration Cacheはタスクグラフ構築を、Build Cacheはタスク出力をキャッシュする。両方を有効にするとビルドの各フェーズで再実行を回避でき、相乗効果が期待できる。

Gradle実行時のトラブルシューティングと注意点

プロキシ設定に関するよくある問題

プロキシ設定で最も多い問題は、HTTPSプロキシの設定漏れです。Maven CentralなどのリポジトリはHTTPSでアクセスされるため、HTTPプロキシだけ設定してもダウンロードに失敗します。エラーメッセージに「Connection refused」や「UnknownHostException」が含まれる場合は、まずHTTPSプロキシの設定を確認しましょう。また、nonProxyHostsの指定が正しくないと、内部リポジトリへのアクセスまでプロキシを経由して失敗することがあります。

認証が必要なプロキシでは、ユーザー名とパスワードが正しく設定されているか確認します。NTLM認証環境ではドメイン指定が必要なこともあります。プロキシの設定はgradle.propertiesのsystemProp.プレフィックスが正しく付いているかも確認ポイントです。プレフィックスがないと単なるGradleプロパティとして扱われ、JVMシステムプロパティとして認識されません。Gradle本体は環境変数http_proxyなどを直接使用しない点も知っておきましょう。

デーモンとメモリに関する問題

ビルドが遅い、または途中で失敗する場合、デーモンのメモリ不足が原因であることが多いです。ガベージコレクションに時間がかかっている兆候がある場合は、org.gradle.jvmargsでヒープサイズを増やします。たとえば-Xmx2048mに設定すると改善することがあります。逆にデーモンが3時間残存してメモリを圧迫しているケースもあるため、CI環境ではorg.gradle.daemon.idletimeoutを短く設定して、ビルド終了後にデーモンを自動停止させるのも有効です。

デーモンの状態はgradle --statusで確認できます。複数のデーモンが起動していてメモリを消費している場合は、gradle --stopで停止できます。デーモンのJVMバージョンがプロジェクトと合っていない場合は、org.gradle.java.homeで別のJVMを指定するか、updateDaemonJvmタスクでデーモン用JVMバージョンを宣言できます。後者は生成されるgradle-daemon-jvm.propertiesをバージョン管理にコミットすることで、チーム全体で同一JVMを強制できます。（出典：Gradle User Manual「Gradle Daemon」）

キャッシュ関連のトラブルと対処

Configuration Cache導入後にビルドが失敗する場合、キャッシュ非互換のビルドスクリプトが原因の可能性があります。Gradle 9.0以降は推奨モードですが、すべてのプラグインやスクリプトが対応しているわけではありません。エラーが発生したらorg.gradle.configuration-cache.problems=warnを設定して警告にフォールバックし、どのタスクが問題を起こしているか特定します。キャッシュエントリが古いと疑われる場合は.gradle/configuration-cacheを削除して再ビルドしましょう。

Build Cacheで注意すべきは、キャッシュが常に正しいとは限らない点です。タスクの入力と出力の関係が正しく宣言されていないと、古いキャッシュが使われて不正確なビルド結果になることがあります。リモートビルドキャッシュのHTTPS通信で証明書エラーが出る場合は、Javaランタイムのトラストストアを更新するか、社内CA証明書を登録します。isAllowUntrustedServer=trueは開発環境の一時的な回避策に限定し、本番ビルドでは使用しないようにしましょう。