保護一般 Java 應用程式

javaapp 用於處理帶有主類的一般 Java 應用程式。它會產生受保護歸檔、各目標平臺的 VLX JRE，以及啟動指令碼。

1. GUI 操作

在應用程式類型頁面選擇 Java 應用。
選擇輸入 JAR、隨包 Java 版本與目標平臺，然後選擇簡單模式或進階模式。
使用進階模式時，視需要填寫主類，並設定 JVM 啟動選項、JavaFX 與排除規則；簡單模式會略過這一頁。各選項的意義請參閱 Protector4J 進階模式設定。
選擇輸出目錄，核對參數摘要，然後點選執行保護。

2. CLI 範例

資訊清單中已經宣告正確的 Main-Class 時：

p4j javaapp app.jar dist

資訊清單中沒有 Main-Class，或需要改用其他啟動類別時，用 --main 指定：

p4j javaapp app.jar dist --main com.example.Main

同時指定主類與 JVM 啟動選項：

p4j javaapp app.jar dist \
  --main com.example.Main \
  --jvm-option -Xms512m \
  --jvm-option -Xmx2g

只保護應用程式的一部分：

p4j javaapp app.jar dist \
  --protect 'com.example.core.**' \
  --exclude 'com.example.core.dto.**'

相容性掃描，以及自動套用掃描建議：

p4j javaapp app.jar --compat-scan
p4j javaapp app.jar dist --compat-apply

這兩個選項不能同時使用，差別如下：

選項	作用	何時使用
`--compat-scan`	只掃描輸入 JAR，印出風險與設定建議後結束；不做編碼，也不產生 `dist`，因此不需要輸出目錄。	初次保護應用程式、升級相依套件或調整保護範圍之後，以及排查相容性問題時，先用它檢視報告。
`--compat-apply`	掃描後合併保守建議，接著繼續編碼並寫出結果，因此必須指定輸出目錄。	已經看過掃描結果並接受這些建議時，用它完成打包；規則驗證過之後的重複建置與 CI 流程也適用。

對 javaapp 而言，--compat-apply 可以依掃描結果追加排除規則，並調整掃描器 ZIP 覆蓋層、JavaFX 與歸檔字尾這三類選項。對這三類選項，命令列中明確指定的值優先。建議排除的類別預設會與你明確寫的 --exclude 合併；若不希望自動追加，同時傳入 --no-compat-excludes 即可。掃描器只做靜態啟發式分析，需要修改程式碼才能解決的問題不會被 --compat-apply 自動修正，打包完成後仍然必須在目標平臺上做迴歸測試。

其他 CLI 命令、全部選項、環境變數與自動化範例，請參閱 CLI 參數參考。

3. 輸出結構

dist/
├── app.p4jx              # 使用 --archive-suffix jar 時產生 app.jar
├── vlxjre/               # 與歸檔和目標平臺相符的執行時
├── lib/                  # 資訊清單 Class-Path 中的相依套件，可選
├── run.sh
├── run.command
├── run.bat
└── README.md

非 class 資源儲存在 P4JX 歸檔的公開資源檢視中。受保護的類別只向掃描器呈現中繼資料樁，真實的方法主體只能由 VLX 執行時載入。

4. 啟動

./run.sh [應用程式參數...]

Windows：

run.bat [應用程式參數...]

不要用系統 JRE 取代輸出目錄中的 vlxjre。如果必須手動啟動，請以產生的指令碼為範本，保留其中的類別路徑、VM 參數與 JavaFX 模組參數。

打包 Windows 目標時，還可以額外產生一個按兩下即可執行的原生啟動程式，它與啟動指令碼並存，詳見產生 Windows EXE 啟動器。

JVM 啟動選項

打包時可以在 GUI 的 JVM 啟動選項中每行填寫一個選項，也可以在命令列中重複使用該選項：

--jvm-option -Xms512m --jvm-option -Xmx2g

若要在已部署的目錄中永久修改：

macOS 與 Linux：編輯 run.sh，在 APP_JAVA_OPTS 判斷之前加上 JVM_OPTS+=("-Xms512m" "-Xmx2g")；run.command 呼叫的是同一份 run.sh。
Windows：編輯 run.bat，在 APP_JAVA_OPTS 判斷之前加上 set "JVM_OPTS=%JVM_OPTS% -Xms512m -Xmx2g"。

臨時選項可以透過 APP_JAVA_OPTS 注入。完整範例與注意事項請見 JVM 啟動選項設定。手動改過的指令碼會在重新打包時被覆寫。

5. 保護範圍建議

預設保護應用程式自身的類別。對正式專案，更建議明確限定自有的商業套件：

--protect 'com.mycompany.product.**'

通常應該排除的類別：

由 Jackson 直接序列化或還原序列化的 DTO 與 record；
欄位或方法被 JNI 存取的類別；
需要被 ORM、相依性注入容器或代理框架改寫的類別；
第三方函式庫與開放原始碼框架；
必須由自訂 ClassLoader 從位元組陣列重新定義的類別。

6. `.p4jx` 與 `.jar` 字尾

p4j javaapp app.jar dist --archive-suffix jar

這個選項只改變檔案名稱，歸檔內容仍然是 P4JX。只有當第三方元件在 URL 或檔案名稱中寫死 .jar 時才需要使用它；它不會把歸檔變成一般的 ZIP 或 JAR。