NetBeans build-impl.xml 編譯失敗「Compile failed」臨時修復與根因分析

NetBeans 專案建置時偶發 build-impl.xml:305: Compile failed，重建即恢復。本文剖析 javac Ant 任務配置、processorpath 與註解處理器機制，揭示「臨時檔案鎖定/殘留」為核心根因，給出永久修復方案。

錯誤現場

nbproject/build-impl.xml:305: Compile failed; see the compiler error output for details.

對應 build-impl.xml 第 305 行附近的 <javac> 任務：

<javac ... fork="yes" includeantruntime="false" ...>
    <compilerarg value="-processorpath"/>
    <compilerarg path="@{processorpath}:${empty.dir}"/>
    <compilerarg line="${ap.processors.internal}"/>
    <compilerarg value="-s"/>
    <compilerarg path="@{apgeneratedsrcdir}"/>
    <compilerarg line="${ap.proc.none.internal}"/>
</javac>

核心根因：Annotation Processor 隔離目錄殘留

1. fork="yes" 另啟 JVM 編譯
2. -processorpath 指向 @{processorpath}:${empty.dir}，${empty.dir} 為臨時空目錄
3. -s @{apgeneratedsrcdir} 產生註解處理器輸出的原始碼
4. 上次建置異常中斷 → 臨時目錄未清理、檔案被鎖定 (Windows)
5. 再次建置時 javac 讀取殘留/鎖定檔案 → 編譯失敗

臨時修復 (官方建議)

1. 選單 Run → Clean and Build Project
2. 或手動刪除 build/、dist/、nbproject/private/
3. 重啟 NetBeans (釋放檔案鎖定)

永久修復方案

1. 關閉不需要的 Annotation Processing

專案右鍵 → Properties → Build → Compiling → 取消勾選 Enable Annotation Processing (若專案未用 Lombok/MapStruct 等)。

2. 獨立 Annotation Processor 輸出目錄

<!-- nbproject/project.properties -->
apgeneratedsrcdir=build/generated-sources/ap-source-output

避免與主源碼目錄混雜，Clean 時可精確刪除。

3. 升級 NetBeans / 遷移至 Maven/Gradle

• NetBeans 12+ (Apache 版) 大幅改善 build-impl.xml 穩定性
• 強烈建議 新專案採用 Maven 或 Gradle，完全擺脫 IDE 專屬建置腳本

4. Maven 專案對應配置 (pom.xml)

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.30</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Ant 任務關鍵屬性解析

總結

「Compile failed」多為 Annotation Processor 臨時目錄殘留/鎖定 導致。短期 Clean & Rebuild，長期 遷移至 Maven/Gradle 徹底解決。