はじめに：./mvnw clean install から一歩進んだMavenの活用
「Mavenを使っているが、普段は ./mvnw clean install しか実行しない」
多くの開発者にとって、このコマンドは強力で十分に機能します。
しかし、プロジェクトが複雑化するにつれて、以下のような課題に直面することがあります。
- 開発環境と本番環境で設定を切り替えたい
- 特定のタスクだけを自動化したい
このような状況では、./mvnw clean install だけでは対応しきれない場面が出てきます。
本記事では、Mavenビルドを効果的に活用するための鍵となるライフサイクル、フェーズ、プラグインの概念を深掘りします。
これらの関係性を理解することで、コマンドの意図を把握し、ビルドプロセスを設計・最適化できるようになります。
対象読者
- Mavenの基本的な概念（Wrapper、GAV、リポジトリなど）を理解している開発者:
本記事はMavenの基礎知識があることを前提としています。 - 普段
./mvnw clean installしか使っていないが、Mavenの機能をより深く活用したいと考えている開発者:
ライフサイクル、フェーズ、プラグインの関連性を理解し、ビルドプロセスの設計・最適化を目指します。 - Spring Bootアプリケーションのビルドプロセスを最適化したい開発者:
spring-boot-maven-pluginの役割やプロファイル活用方法を学びたい方。 - 依存関係の競合やビルドエラーのトラブルシューティング能力を向上させたい開発者:
dependency:treeなどのツールの活用法や解決策を知りたい方。
補足：Mavenの基本概念を再確認する
本記事は、Mavenの基本的な概念（Maven Wrapper、GAV、リポジトリなど）を理解している読者を対象としています。
もしこれらの概念に不安がある場合は、以下の記事を参照して基礎知識を固めてください。
- Maven Wrapperとは？（再現性ビルドの重要性）
- POM.xmlの全体像（GAV、依存関係、リポジトリ）
目次
- 1. ビルドの仕組みを理解する：Mavenのビルドプロセスを「家づくり」で例える
- 1.1. Mavenはなぜライフサイクルを提供するのか？
- 1.2. なぜフェーズとゴールに分かれているのか？
- 1.3. Mavenの基本概念の関係性
- 1.4. Mavenの3つの主要なライフサイクル
- 1.5. 主要なライフサイクルフェーズとデフォルトで紐づくゴール例
- 1.6. コマンドとビルド実行の関連性
- 2. なぜ
./mvnw clean installなのか？：予期せぬビルドエラーを防ぐためのベストプラクティス- 2.1.
cleanを実行しないと何が起こるのか？ - 2.2. ビルドの再現性を担保する重要性
- 2.3. 運用上の注意点：ビルド時間とのバランス
- 2.1.
- 3. Spring Bootにおける主要プラグイン：
spring-boot-maven-plugin- 3.1. なぜ
spring-boot-maven-pluginが不可欠なのか？ - 3.2.
spring-boot-maven-pluginの一般的なカスタマイズ例
- 3.1. なぜ
- 4. 環境ごとのビルド設定切り替え：プロファイル (
<profiles>) の活用- 4.1. なぜプロファイルが必要なのか？解決する課題
- 4.2. 実践例：DB設定をプロファイルで切り替える
- 4.3. プロファイルの様々な活性化条件と活用例
- 4.4.
settings.xmlでのプロファイル設定 - 4.5. プロファイル活用のベストプラクティスと注意点
- 5. 応用編：複雑な依存関係のトラブルシューティング
- 5.1. 依存関係地獄はなぜ起こるのか？
- 5.2. プロジェクトへの影響
- 5.3. 依存関係の可視化と問題の特定：
./mvnw dependency:tree - 5.4. 依存関係競合の解決策：
<exclusions>,<dependencyManagement>, BOM - 5.5. ジュニアエンジニアのためのトラブルシューティングガイド
- 6. まとめ：Mavenビルドの「設計」と「デバッグ」
1. ビルドの仕組みを理解する：Mavenのビルドプロセスを「家づくり」で例える
Mavenのビルドプロセスは「家づくり」に例えることで、その抽象的な概念を直感的に理解できます。
1.1. Mavenはなぜライフサイクルを提供するのか？
Mavenがライフサイクルを提供する主な理由は、ビルドプロセスを標準化し、一貫したビルド結果を得るためです。もしライフサイクルがなければ、プロジェクトごとにビルド手順が異なり、開発者間でビルド方法にばらつきが生じる可能性があります。これはビルドの属人化や再現性の喪失につながります。
ライフサイクルは、ビルドの各工程（コンパイル、テスト、パッケージングなど）を明確に定義し、それらを自動で順番に実行する仕組みです。これにより、誰がいつどこでビルドしても、同じ手順で同じ成果物が得られる「再現性のあるビルド」が保証されます。
1.2. なぜフェーズとゴールに分かれているのか？
ライフサイクルは大きな「工程」ですが、その内部はさらに細かい「段階（フェーズ）」に分かれ、各段階で「具体的な作業（ゴール）」が実行されます。この階層構造は、ビルドの粒度を細かく制御し、必要に応じて特定のタスクのみを実行するためにあります。
例えば、compileフェーズを実行すると、その前のvalidateフェーズも自動的に実行されます。これは、ある作業を行うにはその前提となる作業が完了している必要があるためです。開発者は複雑な依存関係を意識することなく、「ここまで実行してほしい」と指示するだけで済みます。
また、ライフサイクルに紐づかない単一の作業（例：コード生成ツール実行）を実行したい場合は、特定のプラグインの特定のゴールだけを実行することも可能です。
Mavenのビルドプロセスは、以下の構造で構成されます。
1.3. Mavenの基本概念の関係性
- ライフサイクル (Lifecycle):
家づくりの「工程全体」です。Mavenには主に以下の3つのライフサイクルがあります。cleanライフサイクル: ビルド成果物の削除（更地にする工程）defaultライフサイクル: プロジェクトのコアビルド（コンパイル、テスト、パッケージングなど、家を建てる工程）siteライフサイクル: プロジェクトサイトの生成（内覧会用の資料作成工程）
- フェーズ (Phase):
ライフサイクル内の各「段階」です。defaultライフサイクルには、validate（設計図チェック）→compile（部材の加工）→test（強度テスト）→package（棟上げ）といった多数のフェーズが順番に定義されています。 - プラグイン (Plugin):
各段階で実際の作業を行う「専門の職人チーム」です。
例えば、「コンパイル」はmaven-compiler-pluginが担当します。 - ゴール (Goal):
職人が行う「具体的な作業」です。maven-compiler-pluginはcompile（メインのソースをコンパイル）やtestCompile（テストコードをコンパイル）といったゴール（作業）を持っています。
1.4. Mavenの3つの主要なライフサイクル
Mavenには主に3つのライフサイクルがあり、それぞれ異なる目的を持っています。
cleanライフサイクル:
プロジェクトのビルドによって生成された成果物（targetディレクトリなど）を削除します。これにより、クリーンな状態からビルドを開始でき、予期せぬ問題を防ぎます。defaultライフサイクル:
プロジェクトのデプロイメントを処理します。これは、プロジェクトを構築し、テストし、パッケージ化し、そしてローカルリポジトリにインストールしたり、リモートリポジトリにデプロイしたりする主要なビルドフェーズを含みます。siteライフサイクル:
プロジェクトのドキュメントやレポートを生成します。プロジェクトサイトの公開に利用されます。
1.4.1. 図: Mavenの主要なライフサイクルとフェーズ
重要な関係:
ライフサイクルはフェーズの集まりであり、各フェーズには、それを実行するためのプラグインのゴールが紐付けられています。
1.5. 主要なライフサイクルフェーズとデフォルトで紐づくゴール例
Mavenのdefaultライフサイクルでは、以下に示すような主要なフェーズと、それにデフォルトで紐づいているプラグインのゴールが存在します。
これらのゴールは、特別な設定がなければ自動的に実行されます。
| フェーズ名 | デフォルトで紐づくプラグインとゴール | 概要 |
|---|---|---|
validate | maven-antrun-plugin:run（Maven 3以降） | プロジェクトが正しい状態か検証（POMの確認など） |
initialize | （なし、カスタムプラグインで利用） | ビルド状態の初期化。 |
generate-sources | maven-antrun-plugin:run など | ソースコード生成。 |
process-sources | maven-resources-plugin:resources | リソースファイルの処理。 |
compile | maven-compiler-plugin:compile | メインのソースコードをコンパイル。 |
process-classes | （なし、カスタムプラグインで利用） | コンパイル済みクラスの処理。 |
generate-resources | （なし、カスタムプラグインで利用） | リソースファイルの生成。 |
process-resources | （なし、カスタムプラグインで利用） | 生成されたリソースファイルの処理。 |
test-compile | maven-compiler-plugin:testCompile | テストソースコードをコンパイル。 |
process-test-classes | （なし、カスタムプラグインで利用） | コンパイル済みテストクラスの処理。 |
test | maven-surefire-plugin:test | 単体テストを実行。 |
prepare-package | （なし、カスタムプラグインで利用） | パッケージングの準備。 |
package | maven-jar-plugin:jar (JAR) / maven-war-plugin:war (WAR) など | コンパイル済みコードをJAR/WARなどにパッケージング。 |
post-package | （なし、カスタムプラグインで利用） | パッケージング後の処理。 |
verify | maven-failsafe-plugin:integration-test, maven-failsafe-plugin:verify | 統合テストを実行し、検証。 |
install | maven-install-plugin:install | 生成物をローカルリポジトリにインストール。 |
deploy | maven-deploy-plugin:deploy | 生成物をリモートリポジトリにデプロイ。 |
補足:
- 上記はMavenのデフォルト設定における主要な紐付けです。
- プロジェクトの
pom.xmlで設定を変更したり、特定のプラグインを追加したりすることで、紐付けられるゴールは変わる可能性があります。 - 全てのフェーズにデフォルトでゴールが紐付けられているわけではありません。
1.6. コマンドとビルド実行の関連性
./mvnw clean install や ./mvnw compile といったMavenコマンドを実行した際に、内部でどのようなフェーズやゴールが実行されるかを視覚的に見てみましょう。
1.6.1. 図: コマンドとフェーズ・ゴールの実行フロー
図のように、./mvnw compile とコマンドを打つと、Mavenは default ライフサイクルの compile フェーズを実行します。
これは「建築工程のうち、部材の加工まで進めて！」と指示するのと同じです。
Mavenは内部で validate フェーズから順番に実行し、compile フェーズに紐付けられた maven-compiler-plugin:compile ゴールを呼び出して、コンパイル作業を完了させます。
さらに詳しく学ぶ:
ライフサイクル、フェーズ、プラグインについては、以下の記事でさらに詳細に解説しています。基礎をしっかりと固めたい場合は、こちらも併せてご参照ください。
2. なぜ ./mvnw clean install なのか？：予期せぬビルドエラーを防ぐためのベストプラクティス
cleanとdefaultは独立したライフサイクルです。そのため、./mvnw install を実行しても、cleanライフサイクルは自動では実行されません。
では、なぜ clean を付けるのが一般的なのでしょうか？
それは、前回のビルドで生成された古いファイル（targetディレクトリの中身）が、新しいビルドに意図せず混入し、予期せぬエラーや誤動作を引き起こすのを防ぐためです。
2.1. clean を実行しないと何が起こるのか？
具体的な問題として、以下のようなケースが考えられます。
- 古いクラスファイルの残存:
ソースコードを修正・削除しても、以前コンパイルされた古いクラスファイルがtargetディレクトリに残ることがあります。これにより、新しいコードでは使われないはずの古いロジックが実行されたり、存在しないはずのクラスが参照されたりして、デバッグが非常に困難な謎の実行時エラー（例:NoSuchMethodError,NoClassDefFoundError）が発生する可能性があります。 - テストの誤検出:
テストコードやテスト対象のコードを変更した場合でも、以前のテスト結果や古いテストクラスが残っていると、正しいテストが実行されず、誤ったテスト結果（本当は失敗しているのに成功表示されるなど）が表示されることがあります。 - リソースファイルの不整合:
プロパティファイルや設定ファイルなどを変更した際に、古いリソースファイルがビルド成果物に残ってしまい、アプリケーションが意図しない設定で動作することがあります。
これらの問題は、特に大規模なプロジェクトやCI/CD環境において、ビルドの信頼性を著しく低下させます。
2.2. ビルドの再現性を担保する重要性
ビルド前に clean で一度作業ディレクトリをクリーンな状態にしてから install（ビルド成果物の生成とローカルリポジトリへのインストール）を行うことで、毎回クリーンな状態でビルドが開始されます。これにより、誰が、いつ、どこでビルドしても、常に同じ手順で同じ成果物が生成される「ビルドの再現性」が保証されます。これは品質保証の観点からも極めて重要です。
2.3. 運用上の注意点：ビルド時間とのバランス
cleanはビルドの再現性を高める上で非常に重要ですが、プロジェクトによっては全ての依存ライブラリや生成ファイルを削除するため、ビルド時間が長くなる可能性があります。
- メリット:
ビルドの再現性が高く、予期せぬエラーを防ぐことができます。 - デメリット:
ビルドに時間がかかります。
日常の開発で素早く変更を検証したい場合は clean を省略することもありますが、コミット前やリリースビルド、CI/CD環境では必ず clean を実行するのがベストプラクティスです。プロジェクトの規模やビルドの目的に応じて、このバランスを考慮しましょう。
3. Spring Bootにおける主要プラグイン：spring-boot-maven-plugin
Mavenプロジェクトで実行可能なJARを作成する際、通常は maven-jar-plugin を設定します。しかし、Spring Bootプロジェクトではその役割が spring-boot-maven-plugin に置き換わります。
3.1. なぜ spring-boot-maven-plugin が不可欠なのか？
通常のJavaアプリケーションでは maven-jar-plugin を使ってJARファイルを作成し、依存ライブラリは別途クラスパスに指定して実行します。一方、Spring Bootアプリケーションには以下の特徴があり、これらを実現するには特別な仕組みが必要です。
- 自己完結型であること:
依存ライブラリ、アプリケーションコード、そして組み込みのWebサーバー（Tomcat, Jettyなど）をすべて単一のJARファイル（Fat JARまたはUber JARと呼ばれる）に内包し、java -jarコマンド一つで実行できること。 - 特別なクラスローディング:
Fat JAR内部にネストされたJARファイル（依存ライブラリ）は、Javaの標準的なクラスローダーでは読み込むことができません。Spring Bootはこれを解決するために独自のクラスローディングメカニズムを提供します。
これらの要件を満たすために中心となるのが、spring-boot-maven-plugin です。このプラグインは、単にJARを作成するだけでなく、Spring Bootアプリケーションを実行可能な形式に「再パッケージング」する重要な役割を担います。
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<!-- spring-boot-starter-parent使用時はバージョン不要 -->
</plugin>
</plugins>
</build>このプラグインは、packageフェーズでrepackageというゴールを実行します。
このゴールが、Spring Bootアプリケーションを java -jar コマンド一つで起動可能にする「Fat JAR」を作成する上で、極めて重要な役割を果たします。
3.1.1. Fat JARとは？
アプリケーションのクラスファイルだけでなく、すべての依存ライブラリ（JARファイル）を内包した、自己完結型の単一JARファイルです。spring-boot-maven-pluginは、通常のmaven-jar-pluginが作成したJARファイルに、依存関係を詰め込み直し、実行可能な形式に再パッケージング（repackage）します。
spring-boot-maven-pluginが作成するFat JARの内部構造と、それがどのように実行されるかを視覚的に理解しましょう。
3.1.2. 図の解説：Fat JARの「自己完結性」の秘密
上記の図は、Spring BootのFat JARがどのようにして「自己完結型」でアプリケーションを実行しているかの内部構造と起動の流れを示しています。
your-app.jar (Fat JAR):
これがspring-boot-maven-pluginによって生成される単一の実行可能JARファイルです。この中にアプリケーションの実行に必要なすべてがパッケージングされています。アプリケーションコード + リソース類(BOOT-INF/classes):
あなたが書いたJavaコードや、application.propertiesなどの設定ファイルがここに格納されます。通常のJARのclassesディレクトリに相当しますが、Fat JAR内ではBOOT-INF/classesというパスになります。依存ライブラリJAR(BOOT-INF/lib):
アプリケーションが依存する全てのライブラリ（Spring Framework、Webサーバー、データベースドライバなど）が、このディレクトリにネストされたJARファイルとして格納されます。これが自己完結性の鍵です。Spring Bootランチャー:
Spring Bootが提供する特別なクラスローダー（JarLauncherなど）を指します。標準のJavaクラスローダーではネストされたJARファイルを直接読み込めないため、このランチャーが独自のメカニズムでBOOT-INF/lib内のJARをクラスパスにロードします。META-INF/MANIFEST.MF: JARファイルのメタ情報が記述されたファイルです。spring-boot-maven-pluginは、このファイルに以下の重要な情報を書き込みます。Main-Class:
アプリケーション起動時に最初に実行されるクラスとして、Spring Bootランチャーのクラス（例:org.springframework.boot.loader.JarLauncher）が指定されます。Start-Class:
実際のアプリケーションのメインクラス（public static void main(String args[])メソッドを持つクラス）が指定されます。ランチャーがこのクラスを呼び出します。
java -jar your-app.jar:
コマンドを実行すると、JVMはまずMANIFEST.MFのMain-Classに指定されたSpring Bootランチャーを起動します。- 実行フロー:
Spring Bootランチャーは、BOOT-INF/libとBOOT-INF/classesから必要なクラスを独自のクラスローダーでロードし、最終的にStart-Classに指定されたアプリケーションのメインメソッドを呼び出し、Spring Bootアプリケーションが起動します。
3.2. spring-boot-maven-pluginの一般的なカスタマイズ例
spring-boot-maven-pluginは、より詳細な制御を可能にするための設定オプションを多数提供しています。
3.2.1. 特定の依存関係をFat JARから除外する
開発時のみ必要なデータベースドライバー（例: H2 Database）や、テスト時にしか使用しないライブラリなどを最終的なFat JARから除外したい場合があります。これにより、JARのサイズを小さくし、起動を速くできます。
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
</exclude>
<exclude>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>上記の例では、h2データベースとjunit-jupiter-apiをFat JARから除外しています。通常、scope=testやscope=providedに設定された依存関係はデフォルトで除外されますが、明示的に除外したい場合にこの設定を利用できます。
3.2.2. レイヤードJAR（Layered JAR）を有効にする
Spring Boot 2.3以降では、アプリケーションをコンテナイメージとしてデプロイする際に非常に有用な「レイヤードJAR」を生成する機能が追加されました。これは、JARの内部コンテンツを「依存関係（dependencies）」「Spring Bootローダー（spring-boot-loader）」「アプリケーションのスナップショット（snapshot-dependencies）」「アプリケーションコード（application）」といった論理的な層（レイヤー）に分割するものです。
なぜレイヤードJARが役立つのか？
Dockerなどのコンテナイメージは層（レイヤー）で構成されており、変更があった層だけが再ビルドされる特性があります。通常のFat JARでは、小さなアプリケーションコードの変更でも全ての層（依存ライブラリ含む）が再構築されてしまい、コンテナイメージのビルド時間が長くなる傾向にありました。
レイヤードJARを有効にすると、頻繁に変わるアプリケーションコードは最上位のレイヤーに、あまり変わらない依存ライブラリは下位のレイヤーに配置されます。これにより、アプリケーションコードの変更時でも、下位の依存ライブラリ層はキャッシュが効き、コンテナイメージのビルド時間を大幅に短縮できるメリットがあります。
設定例:
spring-boot-starter-parentを使用している場合、追加の設定なしでレイヤードJAR機能が有効になります。もし親POMを使用していない場合は、layers設定を追加します。
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<layers>
<enabled>true</enabled>
</layers>
</configuration>
</plugin>レイヤードJARを生成すると、java -Djarmode=tool -jar target/your-app.jar extract コマンドで各レイヤーの内容を抽出でき、それらを元に効率的なDockerfileを作成できます。
重要: Spring Bootプロジェクトでは、実行可能JARの作成は
spring-boot-maven-pluginに任せるのが一般的です。maven-jar-pluginの<mainClass>などを手動で設定する必要は通常ありません。
4. 環境ごとのビルド設定切り替え：プロファイル (<profiles>) の活用
開発が進むと、以下のように環境ごとに設定やビルド挙動を切り替えたいケースが頻繁に発生します。
- 開発環境ではH2のインメモリDBを、本番環境ではPostgreSQLに接続したい
- 本番ビルドではテストをスキップしたい
- 環境ごとに異なるAPIエンドポイントを設定したい
4.1. なぜプロファイルが必要なのか？解決する課題
これらの要求を手動やソースコードの直接編集で対応しようとすると、以下の課題に直面します。
- 手動設定変更によるミス:
環境ごとにpom.xmlやプロパティファイルを都度編集すると、ヒューマンエラーの原因となり、ビルドの再現性を損なう可能性があります。 - 設定の一元管理の困難さ:
環境固有の設定がプロジェクトのあちこちに散らばると、管理が複雑になり、更新漏れや整合性の問題が発生しやすくなります。 - デプロイプロセスの複雑化:
環境ごとに異なるビルド成果物を手動で生成・管理する必要が生じ、CI/CDパイプラインの構築を妨げます。
これらの課題を解決し、ソースコードを変更せずに、環境ごとに異なる設定やビルド挙動を持つ成果物（JAR）を生成することを可能にするのが、Mavenの強力な機能である プロファイル (<profiles>) です。プロファイルは、インフラや環境の差分をビルド時に吸収するためのメカニズムとして機能します。
プロファイルを使うと、特定の条件下でのみ有効になる設定ブロックをpom.xml内に定義できます。これにより、開発者はpom.xmlを一つだけ管理すればよく、ビルド時に適切なプロファイルを指定するだけで、目的の環境に対応した成果物を得られます。
4.2. 実践例：DB設定をプロファイルで切り替える
プロファイルがどのように機能するか、以下のデータフロー図で見てみましょう。
このデータフローを踏まえ、具体的な設定方法を見ていきましょう。
pom.xmlにプロファイルを定義:dev（開発）プロファイルとprod（本番）プロファイルを定義し、それぞれで異なるプロパティを設定します。
<profiles>
<!-- 開発用プロファイル (デフォルトで有効) -->
<profile>
<id>dev</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<db.url>jdbc:h2:mem:testdb</db.url>
<db.username>sa</db.username>
<db.password></db.password>
</properties>
</profile>
<!-- 本番用プロファイル -->
<profile>
<id>prod</id>
<properties>
<db.url>jdbc:postgresql://prod-db-host:5432/mydb</db.url>
<db.username>prod_user</db.username>
<db.password>prod_password</db.password>
</properties>
</profile>
</profiles>- リソースフィルタリングを有効化:
ビルド時にプロパティをリソースファイルに反映させるため、<build>セクションでリソースフィルタリングを有効にします。
<build>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
...
</build>application.propertiesにプレースホルダを記述:src/main/resources/application.propertiesに、プロファイルで定義したプロパティ名を使ってプレースホルダを記述します。
spring.datasource.url=${db.url}
spring.datasource.username=${db.username}
spring.datasource.password=${db.password}- プロファイルを指定してビルド:
-Pオプションを使って、有効にしたいプロファイルを指定してビルドします。
# 開発プロファイルでビルド (デフォルトなので -Pdev は省略可)
./mvnw clean package
# 本番プロファイルでビルド
./mvnw clean package -Pprod prodプロファイルでビルドすると、targetディレクトリ内に生成される application.properties の ${db.url} は jdbc:postgresql://... に置き換えられます。これにより、同じソースコードから環境ごとに異なる設定を持つ成果物（JAR）をビルドできます。
4.3. プロファイルの様々な活性化条件と活用例
-Pオプションで明示的に指定する以外にも、プロファイルを自動的に有効化する様々な条件を設定できます。
4.3.1. システムプロパティによる活性化
コマンドラインでシステムプロパティを指定することでプロファイルを有効化できます。
<profile>
<id>staging</id>
<activation>
<property>
<name>env</name>
<value>staging</value>
</property>
</activation>
<properties>
<api.url>https://api.staging.example.com</api.url>
</properties>
</profile>ビルドコマンド:
./mvnw clean package -Denv=staging-Denv=staging のようにプロパティを渡すと、staging プロファイルが有効になり、api.url プロパティが https://api.staging.example.com に置き換えられます。
4.3.2. JDKバージョンによる活性化
特定のJDKバージョンでのみ有効にしたいビルドツールや設定がある場合に利用できます。
<profile>
<id>jdk17-features</id>
<activation>
<jdk>17</jdk> <!-- JDK 17 の場合に有効 -->
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<release>17</release>
</configuration>
</plugin>
</plugins>
</build>
</profile>このプロファイルは、MavenがJDK 17で実行された場合に自動的に有効になり、maven-compiler-pluginのreleaseオプションが17に設定されます。
4.3.3. OSによる活性化
オペレーティングシステム（OS）によって異なるビルドスクリプトやプラグインを実行したい場合に利用します。
<profile>
<id>run-windows-script</id>
<activation>
<os>
<family>windows</family>
</os>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>cmd.exe</executable>
<arguments>
<argument>/c</argument>
<argument>my-windows-script.bat</argument>
</arguments>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>run-unix-script</id>
<activation>
<os>
<family>unix</family>
</os>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>sh</executable>
<arguments>
<argument>my-unix-script.sh</argument>
</arguments>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>この例では、OSがWindowsの場合に.batスクリプトを、Unix系（Linux/macOSなど）の場合に.shスクリプトを実行するようにプロファイルを切り替えています。
4.4. settings.xml でのプロファイル設定
pom.xmlに記述するプロファイルはプロジェクト全体で共有されます。
一方、開発者個人の環境に依存する設定（例: 特定の認証情報、ローカルリポジトリのパス、使用したいプロファイルのデフォルト有効化など）は、ユーザーのMaven設定ファイルである settings.xml (~/.m2/settings.xml) に記述することも可能です。
settings.xmlでプロファイルを定義し、<activeProfiles>セクションでデフォルトで有効にするプロファイルを指定することで、pom.xmlを変更せずに個人の開発環境をカスタマイズできます。
<!-- ~/.m2/settings.xml -->
<settings>
<profiles>
<profile>
<id>my-dev-env</id>
<properties>
<dev.database.url>jdbc:h2:file:~/my-dev-db</dev.database.url>
</properties>
</profile>
</profiles>
<activeProfiles>
<activeProfile>my-dev-env</activeProfile>
</activeProfiles>
</settings>4.5. プロファイル活用のベストプラクティスと注意点
プロファイルは強力な機能ですが、利用にはいくつかのベストプラクティスと注意点があります。
4.5.1. activeByDefault の使用は避けるべき
以前の「実践例」でactiveByDefaultを使用しましたが、これは意図しないプロファイルが有効になるリスクがあるため、プロダクションコードでは避けるべきとされています。
- なぜ避けるべきか？:
複数のプロファイルがあり、どれも明示的に有効化されていない場合、activeByDefaultが設定されたプロファイルが自動的に有効になります。新しいプロファイルが追加された際などに、開発者が意図しないプロファイルが有効になり、予期せぬビルド結果や設定ミスを引き起こす可能性があります。 - 代替案:
常に-Pオプションで明示的にプロファイルを指定するか、settings.xmlで開発環境用のプロファイルをデフォルトで有効にするなど、より制御が明確な方法を選ぶべきです。
4.5.2. ビルド時設定と実行時設定の区別
プロファイルは主にビルド時（コンパイル、パッケージング、リソースフィルタリングなど）の設定を切り替えるために使用します。
一方、アプリケーションが稼働中に動的に変更されるべき設定（例: データベース接続情報、外部APIの認証情報など）は、プロファイルではなく、Spring Bootの外部設定機能（application.properties/application.ymlでのプロファイルごとの設定、環境変数、コマンドライン引数など）で管理するべきです。
- プロファイル（ビルド時）での利用例:
- ビルドツールチェーンの切り替え（JDKバージョン、OSごとのシェルスクリプト実行など）
- 特定のプラグインの有効/無効化や設定変更
- リソースフィルタリングによるコンパイル済みコードへの設定埋め込み（例:
api.url）
- Spring Bootの外部設定（実行時）での利用例:
- アプリケーション起動時に動的に読み込まれる設定（DB接続情報、環境変数からの注入、設定サーバーなど）
- これらの設定は、ビルド後にJARファイルを変更することなく、実行環境ごとに調整可能です。
この区別を理解し、適切に使い分けることで、アプリケーションの柔軟性と保守性を高めることができます。
5. 応用編：複雑な依存関係のトラブルシューティング
Mavenを使いこなす上で避けて通れないのが、依存関係の管理です。特に複数のライブラリを組み合わせる大規模なプロジェクトでは、「依存関係地獄 (Dependency Hell)」と呼ばれる問題に直面することがあります。
5.1. 依存関係地獄はなぜ起こるのか？
この問題は、主に以下のシナリオで発生します。
- 推移的依存関係の競合:
プロジェクトが直接依存するライブラリAとライブラリBが、それぞれ異なるバージョンの同じライブラリCに依存している場合です（例: ライブラリAはCommon-Lib:1.0、ライブラリBはCommon-Lib:2.0に依存）。Mavenは「最も近いものが優先される」という解決ルールを持っていますが、このルールだけでは意図しないバージョンのライブラリが採用され、予期せぬ問題を引き起こすことがあります。 - 古いライブラリの残存:
開発が進むにつれてライブラリのバージョンアップが行われますが、古いバージョンのライブラリが完全に置き換えられず、ビルドパスに残ってしまうことがあります。 - 互換性のない変更:
ライブラリのメジャーバージョンアップなどで、後方互換性のない変更（メソッドの削除やシグネチャの変更など）が行われた際、他のライブラリやアプリケーションコードが古いAPIを参照しようとしてエラーになることがあります。
5.2. プロジェクトへの影響
依存関係地獄は、プロジェクトに以下のような深刻な影響を及ぼします。
- 実行時エラー:
最も一般的なのはNoSuchMethodErrorやNoClassDefFoundErrorです。これは、アプリケーションが期待するバージョンのライブラリに存在するクラスやメソッドが見つからない場合に発生し、根本原因の特定に時間がかかることがあります。 - 予期せぬ動作:
異なるバージョンのライブラリが混在することで、アプリケーションの動作が不安定になったり、期待とは異なる結果を返したりすることがあります。 - セキュリティ脆弱性:
古いバージョンのライブラリが意図せず含まれてしまうと、そのライブラリに存在する既知のセキュリティ脆弱性がプロジェクトに残存し、セキュリティリスクを高めます。 - ビルド失敗:
特定の環境でのみビルドが失敗したり、CI/CDパイプラインが不安定になったりすることもあります。
このような問題を解決するために、Mavenは強力なツールとメカニズムを提供しています。
5.3. 依存関係の可視化と問題の特定：./mvnw dependency:tree
依存関係の競合を解決する第一歩は、現状を正確に把握することです。./mvnw dependency:tree コマンドは、プロジェクトの依存関係をツリー形式で表示し、どのライブラリがどのライブラリによって持ち込まれたのかを可視化します。
特に -Dverbose オプションを使用すると、競合によって除外された依存関係も表示されるため、問題の特定に非常に役立ちます。
# プロジェクト全体の依存関係ツリーを表示
./mvnw dependency:tree
# 競合によって除外された依存関係も表示
./mvnw dependency:tree -Dverbose5.3.1. dependency:tree の出力例とその読み解き方
以下は、dependency:tree コマンドの出力例です。
[INFO] --- maven-dependency-plugin:3.6.1:tree (default-cli) @ my-spring-boot-app ---
[INFO] com.example:my-spring-boot-app:jar:0.0.1-SNAPSHOT
[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:3.2.0:compile
[INFO] | +- org.springframework.boot:spring-boot-starter:jar:3.2.0:compile
[INFO] | | +- org.springframework.boot:spring-boot:jar:3.2.0:compile
[INFO] | | +- org.springframework.boot:spring-boot-autoconfigure:jar:3.2.0:compile
[INFO] | | +- org.springframework.boot:spring-boot-starter-logging:jar:3.2.0:compile
[INFO] | | | +- ch.qos.logback:logback-classic:jar:1.4.11:compile
[INFO] | | | | +- ch.qos.logback:logback-core:jar:1.4.11:compile
[INFO] | | | | \- org.slf4j:slf4j-api:jar:2.0.9:compile
[INFO] | | | +- org.apache.logging.log4j:log4j-to-slf4j:jar:2.20.0:compile
[INFO] | | | | \- org.apache.logging.log4j:log4j-api:jar:2.20.0:compile
[INFO] | | | \- org.slf4j:jul-to-slf4j:jar:2.0.9:compile
[INFO] | | \- jakarta.annotation:jakarta.annotation-api:jar:2.1.1:compile
[INFO] | +- org.springframework.boot:spring-boot-starter-json:jar:3.2.0:compile
[INFO] | | +- com.fasterxml.jackson.core:jackson-databind:jar:2.15.3:compile
[INFO] | | | +- com.fasterxml.jackson.core:jackson-annotations:jar:2.15.3:compile
[INFO] | | | \- com.fasterxml.jackson.core:jackson-core:jar:2.15.3:compile
[INFO] | | +- com.fasterxml.jackson.datatype:jackson-datatype-jdk8:jar:2.15.3:compile
[INFO] | | +- com.fasterxml.jackson.datatype:jackson-datatype-jsr310:jar:2.15.3:compile
[INFO] | | \- com.fasterxml.jackson.module:jackson-module-parameter-names:jar:2.15.3:compile
[INFO] | +- org.springframework:spring-web:jar:6.1.1:compile
[INFO] | \- org.springframework:spring-webmvc:jar:6.1.1:compile
[INFO] +- org.projectlombok:lombok:jar:1.18.30:provided
[INFO] +- org.springframework.boot:spring-boot-starter-test:jar:3.2.0:test
[INFO] | +- org.springframework.boot:spring-boot-test:jar:3.2.0:test
[INFO] | +- org.springframework.boot:spring-boot-test-autoconfigure:jar:3.2.0:test
[INFO] | +- com.jayway.jsonpath:json-path:jar:2.8.0:test
[INFO] | | +- net.minidev:json-smart:jar:2.5.0:test
[INFO] | | | \- net.minidev:accessors-smart:jar:2.5.0:test
[INFO] | | | \- org.ow2.asm:asm:jar:9.3:test
[INFO] | | \- org.slf4j:slf4j-api:jar:2.0.9:test
[INFO] | +- jakarta.xml.bind:jakarta.xml.bind-api:jar:4.0.1:test
[INFO] | +- org.assertj:assertj-core:jar:3.24.2:test
[INFO] | +- org.hamcrest:hamcrest:jar:2.2:test
[INFO] | +- org.mockito:mockito-core:jar:5.7.0:test
[INFO] | | \- net.bytebuddy:byte-buddy:jar:1.14.9:test
[INFO] | | \- net.bytebuddy:byte-buddy-agent:jar:1.14.9:test
[INFO] | +- org.mockito:mockito-junit-jupiter:jar:5.7.0:test
[INFO] | +- org.skyscreamer:jsonassert:jar:1.5.1:test
[INFO] | | \- com.vaadin.external.google:android-json:jar:0.0.20131108.vaadin1:test
[INFO] | +- org.springframework:spring-core:jar:6.1.1:test
[INFO] | | \- org.springframework:spring-jcl:jar:6.1.1:test
[INFO] | +- org.springframework:spring-test:jar:6.1.1:test
[INFO] | \- org.xmlunit:xmlunit-core:jar:2.9.1:test
[INFO] \- commons-logging:commons-logging:jar:1.1.1:compile -> 1.2:compileこの出力からは、以下の情報を読み取ることができます。
- 依存関係の階層構造:
+-や\で示されるインデントによって、どのライブラリがどのライブラリに依存しているか（推移的依存関係）が一目でわかります。 - バージョン情報:
各ライブラリのgroupId:artifactId:packaging:version:scopeが明記されており、どのバージョンのライブラリが使用されているかを確認できます。 - スコープ:
compile,provided,testなどのスコープ情報も確認できます。 - 競合解決:
commons-logging:commons-logging:jar:1.1.1:compile -> 1.2:compileのように、同じライブラリの異なるバージョンが検出され、Mavenが1.2の方を採用したことが示されています。-Dverboseオプションを使用すると、このような競合解決の具体的な理由（例: 「最も近いものが優先された」）も表示されます。
このコマンドの出力を見ることで、意図しないバージョンのライブラリが採用されていないか、あるいは特定のライブラリが余分にプロジェクトに含まれていないかを確認できます。
5.4. 依存関係競合の解決策：<exclusions>, <dependencyManagement>, BOM
dependency:tree で問題が特定できたら、以下のメカニズムを活用して解決します。
<exclusions>:
特定の依存ライブラリが推移的に持ち込む不要な依存関係を、ピンポイントで除外するために使用します。例えば、あるライブラリが古いバージョンのCommon-Libを持ち込み、それが原因で競合が発生している場合に、その古いCommon-Libを除外できます。<dependencyManagement>:
プロジェクト全体で利用する依存関係のバージョンを一元的に管理するための仕組みです。親POMや親pom.xmlの<dependencyManagement>セクションでバージョンを定義することで、推移的依存によって異なるバージョンが持ち込まれそうになった場合でも、定義したバージョンが強制的に適用されます。これにより、プロジェクトのどの部分でも常に同じバージョンのライブラリが使われることが保証され、バージョンの不整合による問題を未然に防ぐことができます。- BOM (Bill of Materials):
<dependencyManagement>の応用で、特定のプロダクト（例: Spring Boot, Spring Cloud, Hibernateなど）が提供する、互換性がテストされたライブラリのバージョンリストをインポートする仕組みです。BOMを利用することで、開発者は個々のライブラリのバージョンを意識することなく、フレームワークが推奨する最適な組み合わせで依存関係を管理でき、バージョン間の互換性問題を心配する必要がなくなります。
5.5. ジュニアエンジニアのためのトラブルシューティングガイド
Mavenのビルドエラーや依存関係の問題に直面した際に、効率的に原因を特定し解決するためのヒントをまとめました。
5.5.1. エラーメッセージを正しく読む
エラーメッセージは、問題解決の最も重要な手がかりです。特に、[ERROR]で始まる行やスタックトレースを注意深く読みましょう。
NoSuchMethodErrorやNoClassDefFoundError:
これらは典型的な依存関係のバージョン衝突を示唆しています。期待されるクラスやメソッドが見つからない、または異なるバージョンのライブラリがロードされている可能性があります。Artifact not found:
指定された依存関係やプラグインがMavenのリポジトリ（ローカルまたはリモート）で見つからないことを意味します。タイプミス、ネットワーク接続の問題、リポジトリ設定の誤り、またはアーティファクトがまだデプロイされていない可能性をチェックします。
5.5.2. デバッグコマンドを積極的に活用する
Mavenには、ビルドの詳細な情報を出力するためのコマンドオプションがあります。
-Xまたは--debug(詳細デバッグ出力):./mvnw clean install -X
このコマンドは、Mavenが実行する内部プロセス、どのプラグインがどのゴールを実行しているか、クラスローディングのパス、解決されたプロパティなど、非常に詳細なデバッグログを出力します。ログ量は膨大になりますが、問題の根本原因を特定する上で強力な手がかりとなります。-eまたは--errors(完全なスタックトレース):./mvnw clean install -e
エラーが発生した場合に、例外の完全なスタックトレースを表示します。これにより、どのコードパスで問題が発生したかを正確に把握できます。-Xと併用することもよくあります (./mvnw clean install -X -e)。mvn help:effective-pom(最終的なPOMの確認):./mvnw help:effective-pom > effective-pom.xml
親POMの継承、プロファイルの適用、プロパティの置換など、すべての設定が解決された後の最終的なpom.xmlの内容を標準出力に出力します（ファイルにリダイレクトするのが一般的です）。これにより、意図しない設定が適用されていないかを確認できます。mvn dependency:analyze(依存関係の分析):./mvnw dependency:analyze
このコマンドは、プロジェクトの依存関係を分析し、「使用されていない宣言済みの依存関係 (Used undeclared dependencies)」や「使用されているが宣言されていない依存関係 (Unused declared dependencies)」を報告してくれます。これにより、pom.xmlを整理し、潜在的な問題（必要な依存関係が推移的にのみ提供されているなど）を早期に発見できます。
5.5.3. IDEのMavenツールを活用する
IntelliJ IDEAやEclipseなどの統合開発環境（IDE）には、Mavenの依存関係を視覚的に表示するツールが備わっています。
- 依存関係階層ビューア:
IDEのMavenツールウィンドウ（IntelliJ IDEAの場合）や「Dependency Hierarchy」タブ（Eclipseの場合）を使用すると、dependency:treeの出力をよりグラフィカルでインタラクティブな形で確認できます。競合している依存関係が色付けされたり、簡単に除外設定を追加できたりする機能もあります。
5.5.4. ローカルMavenリポジトリをクリアする
~/.m2/repository にあるローカルリポジトリが破損しているか、古いバージョンのアーティファクトがキャッシュされていることが原因でビルドエラーが発生することがあります。
- クリアする方法:
~/.m2/repositoryディレクトリの内容を完全に削除し（プロジェクトの再ビルドには時間がかかります）、再度ビルドを実行します。rm -rf ~/.m2/repository
または、特定の依存関係のみをクリアする場合は、その依存関係のフォルダのみを削除します。
（例:rm -rf ~/.m2/repository/com/example/my-problem-artifact）
これにより、Mavenは必要な依存関係をリモートリポジトリから afresh でダウンロードし直します。
これらのトラブルシューティング手法を習得することで、Mavenビルドに関する問題に迅速かつ効果的に対処できるようになります。
6. まとめ：Mavenビルドの「設計」と「デバッグ」
本記事では、Mavenビルドを深く理解し、効果的に活用するための概念と実践的な方法を解説しました。
- ビルドプロセスの理解:
ライフサイクル（工程）、フェーズ（段階）、プラグイン（職人）、ゴール（作業）の関係性を「家づくり」の比喩と共に理解することで、Mavenのビルドプロセスを意図を持って設計できるようになります。視覚的な図解を通じて、全体像を把握できました。 ./mvnw clean installの重要性:cleanコマンドでビルド環境をクリーンに保つことが、ビルドの再現性を高め、予期せぬエラーを防ぐ上でなぜ重要なのかを、具体的な問題例と共に深く掘り下げました。- Spring Bootにおけるプラグインの役割:
spring-boot-maven-pluginが、Spring Bootアプリケーションの自己完結型Fat JAR作成に不可欠である理由、その内部構造、動作原理、そしてレイヤードJARのような応用設定について解説しました。 - プロファイルによる環境対応:
<profiles>とリソースフィルタリングを組み合わせることで、ソースコードを変更せずに、環境ごとに異なる設定を持つアプリケーションをビルドする方法や、その様々な活性化条件、データフローを実践的に学びました。 - 依存関係トラブルシューティング:
「依存関係地獄」が発生する原因と影響を理解し、dependency:treeを用いた問題特定から、<exclusions>、<dependencyManagement>、BOMを活用した解決策、さらにはmvn -Xやmvn dependency:analyzeなどのデバッグコマンドまで、具体的な対処法を習得しました。
Mavenは単なるビルドツールではなく、プロジェクトの品質、安定性、開発効率を大きく左右する「ビルドの設計フレームワーク」です。今回学んだ知識と、その背景にある「なぜそうするのか」という理由を土台に、プロジェクトに最適なビルドプロセスを設計し、問題発生時には自信を持ってデバッグ・解決に貢献してください。
免責事項
本記事の内容は、公開時点での情報に基づいて作成されており、正確性には万全を期しておりますが、その内容の完全性、正確性、有用性について保証するものではありません。
技術情報は常に変化しており、将来的に内容が変更される可能性があります。
本記事の情報を利用したことにより生じるいかなる損害についても、当方は一切の責任を負いません。
個々のプロジェクトや環境に適用する際は、必ずご自身の責任と判断において行ってください。
