概要: GradleはJavaプロジェクトのビルドを自動化する強力なツールです。この記事では、Gradleを使ったタスク実行方法、アプリケーションの起動方法、ログ出力の制御方法を基礎から解説します。また、ローカルJARの追加方法やSpring Bootとの連携についても紹介します。
GradleとGradle Wrapperの基本：プロジェクトでの正しい使い方
GradleはJavaなどのJVMプロジェクトで利用できるビルド自動化ツールです。コンパイル、テスト、依存関係管理、JAR作成などの処理をタスクとして自動化できます。重要なのは、GradleのバージョンとJavaのバージョンは別物であるという点です。
Gradle Wrapperを使う理由と基本的な仕組み
Javaプロジェクトでは、Gradle本体を手動インストールしてgradleコマンドを使うより、Gradle Wrapper（gradlew / gradlew.bat）を使うことが公式推奨です。Wrapperはプロジェクトごとに使用するGradleバージョンを固定し、必要なバージョンのGradleを自動取得して実行する仕組みです。これにより、開発者全員やCI環境で同じGradleバージョンを使用でき、ビルド結果の再現性が高まります。（出典：Gradle「Wrapper Basics」）
Wrapperの構成ファイルと確認ポイント
Gradle Wrapperは主に以下のファイルで構成されています。
gradlew：Linux/macOS用の実行スクリプトgradlew.bat：Windows用の実行スクリプトgradle/wrapper/gradle-wrapper.properties：Gradleのバージョン情報を格納gradle/wrapper/gradle-wrapper.jar：Wrapperの実行に必要なJAR
既存プロジェクトに参加した場合は、まずgradlewの有無とgradle-wrapper.propertiesに記載されたGradleバージョンを確認します。
Gradle実行に必要なJDKバージョン
2026年8月時点で、Gradleを実行するにはJDK 17以上が必要です。Java 21でGradleを実行するにはGradle 8.5以降、Java 26で実行するにはGradle 9.4.0以降が必要になります。システムにインストールしたGradleとWrapperのバージョンが異なるとビルド結果が変わる可能性があるため、gradleコマンドとgradlewは混用しないことが重要です。（出典：Gradle「Compatibility Matrix」）
要点：既存プロジェクトではシステムのGradleではなく、必ずGradle Wrapper（gradlew）を使用する。Gradleの実行にはJDK 17以上が必要で、JavaとGradleの互換性確認が不可欠。
Gradleでアプリケーションを実行する方法：runタスクとbootRunの使い分け
GradleでJavaアプリケーションを実行する方法は、使用するプラグインによって異なります。applicationプラグインのrunタスクと、Spring BootプラグインのbootRunタスクが代表的な実行手段です。両者は役割が似ていますが、提供元と機能に違いがあります。
applicationプラグインのrunタスク
runタスクは、applicationプラグインを適用したプロジェクトで使用できます。Javaアプリケーションをコンパイルしてから実行するタスクで、メインクラスの指定が必要です。アプリケーションへの引数は--argsオプションで渡せます。例えば、./gradlew run --args='--spring.profiles.active=dev'のように実行できます。この--argsオプションはapplicationプラグインが提供する機能で、Spring BootのbootRunタスクでも利用可能です。
Spring BootのbootRunタスク
Spring Boot Gradleプラグインを適用すると、bootRunタスクが追加されます。このタスクはSpring Bootアプリケーションを開発時に実行するためのもので、クラスパスの設定や再起動機能などがSpring Boot向けに最適化されています。bootRunはrunタスクと同様に--argsオプションでアプリケーション引数を渡せます。開発中にアプリケーションを起動して動作確認する場合は、通常bootRunを使用します。
runタスクとbootRunの比較
| 項目 | runタスク | bootRunタスク |
|---|---|---|
| 提供元 | applicationプラグイン | Spring Boot Gradleプラグイン |
| 主な用途 | 一般的なJavaアプリケーションの実行 | Spring Bootアプリケーションの開発時実行 |
| 引数渡し | –argsオプションで可能 | –argsオプションで可能 |
| Spring Boot固有機能 | なし | クラスパス最適化などSpring Boot向け設定あり |
要点：Spring BootプロジェクトではbootRun、一般的なJavaアプリケーションではrunを使用する。引数はどちらも--argsで渡せる。
Gradleのタスク実行を制御するコマンドラインオプション解説
Gradleのコマンドラインオプションを使うと、タスクの除外や実行継続、実行計画の確認などを細かく制御できます。開発効率を高めるため、主要なオプションの使い方を理解しておくことが重要です。
タスクの除外と実行継続を制御するオプション
代表的な制御オプションは以下の通りです。
-x/--exclude-task：指定したタスクをビルドから除外する。例：./gradlew build -x testでテストをスキップ--continue：タスクが失敗しても、独立した他のタスクの実行を継続する--rerun-tasks：UP-TO-DATE判定を無視して全タスクを強制再実行する--dry-run：タスクを実際には実行せず、実行予定のタスク一覧のみ表示する
-x testはビルド時にテストをスキップしたい場合に便利です。--continueは複数のコンパイルエラーをまとめて確認したい場合に役立ちます。
ビルドキャッシュと並列実行のオプション
ビルドの高速化に関わるオプションも重要です。
--build-cache：ビルドキャッシュを有効化して再利用可能な成果物をキャッシュする--no-build-cache：ビルドキャッシュを無効化する--parallel：複数プロジェクトを並列実行する--max-workers <数値>：最大ワーカー数を指定する--offline：オンラインリポジトリにアクセスせず、キャッシュのみで実行する--refresh-dependencies：依存関係のキャッシュを更新して再解決する
--offlineはCI環境での再現性確認に有用ですが、依存関係の更新が反映されないため常時使用は避けるべきです。
タスク実行状態の見方とUP-TO-DATEの仕組み
Gradle実行時、タスクには実行状態が表示されます。UP-TO-DATEは入力（ソースファイルなど）に変更がないためスキップされたことを意味し、Gradleの増分ビルド機能によるものです。FROM-CACHEはビルドキャッシュから復元されたことを、NO-SOURCEは実行対象のソースが存在しないことを示します。強制的に再実行したい場合は--rerun-tasksを指定します。
要点：-xでタスク除外、--continueで失敗後も継続、--dry-runで実行計画確認ができる。UP-TO-DATEは増分ビルドによる正常なスキップ表示。
Gradleのログレベルと出力先を理解して効率的にデバッグする
Gradleのログ出力はレベルによって詳細度を切り替えられます。デフォルトのLIFECYCLEレベルでは表示されない情報も、-iや-dオプションで確認できます。適切なログレベルを選ぶことで、効率的なデバッグが可能になります。
ログレベルの種類と切り替えオプション
Gradleのログレベルは詳細な順に以下の通りです。
- DEBUG（
-d/--debug）：最詳細。トラブルシューティング専用で出力が非常に多い - INFO（
-i/--info）：タスクの詳細な実行状況を確認できる - LIFECYCLE（デフォルト）：ビルドの主要な進行状況を表示
- WARN：警告のみ表示
- QUIET（
-q/--quiet）：エラーのみ表示
通常のデバッグでは-iで十分な情報が得られます。-dは大量の出力になるため、詳細な調査が必要な場合に限定して使用します。
警告表示とスタックトレースの制御
警告表示は--warning-modeで制御できます。デフォルトはsummaryで警告件数のみ表示され、allで全警告を表示、noneで警告を抑制できます。エラー発生時のスタックトレースは-s（--stacktrace）でトリミング版を、-S（--full-stacktrace）で完全版を表示できます。
コンソール出力形式とログ出力先
コンソール表示は--consoleオプションで切り替えられます。plainを指定するとカラー出力やプログレスバーを無効化し、プレーンなテキストログになります。これはCIなどでログを保存する場合に有用です。タスクの実行ログはタスクごとにbuild/ディレクトリ内のレポートファイルにも出力されます。テスト結果の詳細はbuild/reports/tests/test/にHTMLレポートとして生成されます。
要点：通常のデバッグは-i（INFO）で十分。CIでは--console plainを指定する。テスト結果はbuild/reports/tests/test/のHTMLレポートで確認できる。
GradleでローカルJARを追加する方法と依存関係管理の実践
Gradleの依存関係管理では、Maven Centralなどのリモートリポジトリからライブラリを取得するのが基本です。しかし、社内ライブラリや独自にビルドしたJARなど、ローカルにあるJARファイルを依存関係に追加したいケースもあります。ここではJARの種類とローカルJARの扱い方を解説します。
通常のJARと実行可能JAR（fat JAR）の違い
./gradlew jarで作成される通常のJARは実行可能JARではなく、依存ライブラリを含みません。そのため、単体でjava -jarを実行しても「no main manifest attribute」や「ClassNotFoundException」エラーが発生します。依存ライブラリを含む単一ファイルのJARはfat JAR（uber JAR）と呼ばれ、ShadowプラグインのshadowJarタスクやSpring BootプラグインのbootJarタスクで作成できます。
Spring BootのbootJarタスクとJAR生成の設定
Spring Boot Gradleプラグインを適用するとbootJarタスクが追加され、依存ライブラリを含む実行可能なfat JARが生成されます。Spring Boot 2.5以降では、jarタスクとbootJarタスクの両方がデフォルトで有効です。生成されるファイルはbuild/libs/にプロジェクト名-バージョン.jarとして出力されます。bootJarタスクの設定では、mainClassで起動クラスを指定したり、archiveFileNameで出力ファイル名をカスタマイズできます。./gradlew buildを実行するとbootJarも自動的に実行されます。
依存関係の調査とトラブルシューティング
依存関係の問題を解決するためのコマンドが用意されています。
./gradlew dependencies：依存関係ツリー全体を表示する./gradlew dependencyInsight --dependency <groupId>:<artifactId>：特定の依存関係がどこから来ているか、どのバージョンが選択されたかを調査する--refresh-dependencies：リモートリポジトリのメタデータを強制的に再取得し、キャッシュの不整合を解消する
「Could not resolve」エラーが発生した場合は、リポジトリ設定の確認と--refresh-dependenciesでの再取得を試します。依存関係の競合やバージョン不整合はdependencyInsightで原因を特定できます。
要点：通常のjarタスクは実行可能JARではない。実行可能JARが必要ならSpring BootのbootJarかShadowプラグインを使用する。依存関係の問題はdependenciesとdependencyInsightで調査できる。
まとめ
よくある質問
Q: Gradleでアプリケーションを実行するにはどうすればいいですか？
A: applicationプラグインを適用している場合は、`./gradlew run` コマンドで実行できます。また、Spring Bootプロジェクトでは `./gradlew bootRun` を使用します。さらに、`–args` オプションを使うとアプリケーションに引数を渡せます。
Q: Gradleのタスクをスキップするにはどうすればいいですか？
A: `-x` または `–exclude-task` オプションを使用します。例えば、テストをスキップしてビルドするには `./gradlew build -x test` と実行します。また、`–continue` オプションを使うと、失敗したタスクがあっても他のタスクを継続できます。
Q: GradleでローカルのJARファイルを依存関係に追加する方法を教えてください。
A: `build.gradle` の `dependencies` ブロックで `implementation files(‘libs/xxx.jar’)` のように記述するか、`flatDir` リポジトリを設定して `implementation name: ‘xxx’` と指定します。
Q: Gradleのログ出力を詳細にするにはどうすればいいですか？
A: `–info` または `-i` オプションでINFOレベル、`–debug` または `-d` オプションでDEBUGレベル（最も詳細）のログを出力できます。通常の作業では `-i` で十分な情報が得られます。
Q: Gradleで実行可能なJARを作成するにはどうすればいいですか？
A: 通常の `jar` タスクで作成されるJARは実行可能ではありません。Spring Bootでは `bootJar` タスクが実行可能なJAR（fat JAR）を作成します。それ以外ではShadowプラグインなどの追加プラグインが必要です。
