Maven 錯誤解決：Non-resolvable parent POM — 父項目未安裝至本地倉庫

錯誤現象

Maven 多模組專案建構時拋出：

Non-resolvable parent POM for ...: Could not find artifact com.example:parent:pom:1.0-SNAPSHOT and 'parent.relativePath' points at wrong local POM

根因分析

Maven 解析子模組 POM 時，需先定位父 POM。解析順序：

1. 本地倉庫（~/.m2/repository）查找對應 GAV。
2. 若 <relativePath> 指定（預設 ../pom.xml），嘗試讀取相對路徑文件。
3. 遠端倉庫下載（若父 POM 已部署）。

常見原因：父模組（或依賴的公共模組）**未先執行 mvn install 安裝至本地倉庫**，導致步驟 1、2 失敗（相對路徑錯誤或文件不存在），步驟 3 遠端無快照版 → 報錯。

解決方案：按依賴順序安裝

1. 先安裝父模組：在父項目根目錄執行 mvn clean install -DskipTests。
2. 再安裝公共依賴模組（如 common、core）：進入各模組目錄執行 mvn clean install -DskipTests。
3. 最後建構聚合/業務模組：在聚合模組目錄執行 mvn clean package 或 mvn clean deploy。

圖示操作流程

右鍵父項目 → Run As → Maven install。

同樣對 common、parent 等被依賴模組執行 install。

IDE 一鍵操作

• IntelliJ IDEA：Maven 邊欄 → 對應模組 → Lifecycle → install。
• Eclipse：右鍵項目 → Run As → Maven install。

進階避坑指南

1. 顯式指定 relativePath：若父子目錄非標準結構，在子模組 POM 中聲明：

   <parent>
       <groupId>com.example</groupId>
       <artifactId>parent</artifactId>
       <version>1.0-SNAPSHOT</version>
       <relativePath>../parent/pom.xml</relativePath> <!-- 明確相對路徑 -->
   </parent>

2. 使用 Maven Reactor：在聚合根 POM 執行 mvn clean install，Reactor 會自動按依賴拓撲序建構所有模組，**無需手動逐個 install**。
3. 快照版本更新策略：開發階段用 -SNAPSHOT，mvn clean install -U 強制更新本地快照。
4. 私服部署：團隊協作建議搭建 Nexus/Artifactory，父 POM 發布至私服，避免各開發機器重複 install。

總結

「先安裝被依賴模組，再建構依賴模組」 是 Maven 多模組開發的鐵律。養成在聚合根目錄執行 mvn clean install 的習慣，讓 Reactor 自動處理建構順序，徹底杜絕「找不到父 POM」錯誤。