IntelliJ IDEA 報「找不到類」異常？三大常見原因與快速排查

初次使用 IntelliJ IDEA 時，專案明明能編譯通過，運行卻拋出 ClassNotFoundException 或「Cannot resolve symbol」。這通常不是程式碼錯，而是專案配置、建構產物或啟動設定不一致導致。以下三大原因覆蓋 90% 的情況。

原因一：XML 配置檔（Spring/MyBatis/Hibernate）未被複製到輸出目錄

IDEA 預設只將 src/main/java 下的 .java 編譯到 target/classes，資源檔（.xml、.properties、.yml）若放在 java 目錄下，需額外配置才會被複製。

解決：在 pom.xml 添加資源過濾

<build>
  <resources>
    <resource>
      <directory>src/main/java</directory>
      <includes>
        <include>**/*.xml</include>
        <include>**/*.properties</include>
        <include>**/*.yml</include>
      </includes>
      <filtering>false</filtering>
    </resource>
    <resource>
      <directory>src/main/resources</directory>
    </resource>
  </resources>
</build>

修改後執行 Maven → Reload Project 或 Build → Rebuild Project。

原因二：類確實不存在（拼寫錯誤、依賴缺失、模組未編譯）

• 拼寫/大小寫錯誤：UserServcie vs UserService，檢查 import 語句。
• Maven 依賴未下載/版本衝突：在 Maven 面板點擊「Reload All Maven Projects」，或刪除 ~/.m2/repository 對應目錄重新下載。
• 多模組專案：依賴模組未安裝：執行 mvn install -DskipTests 將上游模組安裝到本地倉庫。

原因三：Run/Debug Configuration 設定錯誤

啟動配置決定了 classpath、工作目錄、主類、JRE 等關鍵參數。

檢查清單

1. Main class：是否指向正確的啟動類（含 public static void main）。
2. Use classpath of module：選擇包含該主類的模組，確保編譯輸出與依賴在 classpath 中。
3. JRE：專案語言級別（如 Java 17）與所選 JRE 一致。
4. Working directory：若程式碼用相對路徑讀取檔案，需設為專案根目錄或模組目錄。
5. Before launch：確保包含 Build 或 Build, no error check，否則運行的是舊產物。

快速自癒操作（依序嘗試）

1. File → Invalidate Caches / Restart → Invalidate and Restart（清除索引快取）
2. Maven → Reload All Maven Projects（重新解析依賴）
3. Build → Rebuild Project（全量重建）
4. 檢查 target/classes 或 out/production 下是否真有對應 .class 檔案
5. 若為 Spring Boot：嘗試 ./mvnw spring-boot:run 命令列啟動，排除 IDE 配置問題

進階：啟用編譯輸出診斷

Settings → Build, Execution, Deployment → Compiler
☑ Build process heap size (Mbytes): 1024
☑ Use shared build process
☑ Clear output directory on rebuild

若問題持續，查看 Build 輸出視窗的詳細錯誤堆疊，或啟用 Settings → Build → Compiler → Debug logging 獲取更多線索。

總結：資源檔未複製、依賴缺失、啟動配置錯誤是 IDEA 「找不到類」的三大元兇，按上述步驟逐項排查即可快速定位解決。