Maven Archetype 常見 Bug：Source Folder 錯誤標記與修復方案

問題現象

使用 Maven Archetype 創建項目後，IDEA/Eclipse 提示 The folder is already a source folder，但文件系統中 src/main/java、src/test/java 目錄實際不存在。

根本原因

• Archetype 模板中預置了 .classpath 或 .project 文件，標記了源碼目錄。
• Maven 生成項目時複製了這些 IDE 元數據，但未創建對應物理目錄。
• IDE 讀取元數據認為目錄已存在，實際文件系統卻無此目錄，產生衝突。

標準 Maven 目錄結構

project-root/
├── src/
│   ├── main/
│   │   ├── java/        # Java 源碼
│   │   └── resources/   # 配置文件、資源
│   └── test/
│       └── java/        # 測試代碼
├── pom.xml
└── target/              # 編譯輸出 (自動生成)

修復步驟 (IDEA 為例)

1. 右鍵項目 → Open Module Settings (或 F4)。
2. 選中 Modules → Sources 標籤。
3. 找到標記為 Missing (紅色) 的 src/main/java、src/test/java。
4. 選中它們 → 點擊 Remove (減號圖標) 移除錯誤標記。
5. 在文件系統中手動創建對應目錄：
   mkdir -p src/main/java src/main/resources src/test/java
6. 回到 IDEA，點擊 Add Content Root 或直接標記剛創建的目錄為 Sources/Test Sources。
7. 點擊 Apply/OK，IDE 重新索引，問題解決。

Eclipse 修復對應操作

1. 右鍵項目 → Properties → Java Build Path → Source 標籤。
2. 移除標記為 Missing 的源碼路徑。
3. 在 Package Explorer 中右鍵 src/main → New → Source Folder → 命名 java。
4. 同理創建 src/test/java、src/main/resources。

根治方案：優化 Archetype 模板

若你維護內部 Archetype，請在 archetype-resources 中：

• 刪除 .classpath、.project、.idea/ 等 IDE 專屬文件。
• 在 src/main/java、src/test/java 下放置 .keep 空文件（確保 Git 追蹤空目錄）。
• 使用 archetype:create-from-project 從乾淨項目生成模板。

最佳實踐建議

• 新項目優先用 Spring Initializr (start.spring.io) 生成，再導入 IDE，避免 Archetype 坑。
• 團隊統一 IDE 設置導出/導入 (File → Manage IDE Settings → Export/Import Settings)。
• 使用 maven-clean-plugin 清理時保護源碼目錄：
  <configuration><excludeDefaultDirectories>true</excludeDefaultDirectories></configuration>