保護普通 Java 應用

javaapp 用於帶主類的普通 Java 應用。它生成受保護歸檔、目標平臺 VLX JRE 和啟動指令碼。

1. GUI 操作

在應用型別頁面選擇 Java Application。
選擇輸入 JAR、隨包 Java 版本和目標平臺，並選擇簡單模式或高階模式。
使用高階模式時，按需填寫 Main class，並配置 JVM 引數、JavaFX 和排除規則；簡單模式可跳過此頁。各選項含義見 Protector4J 高階模式設定。
選擇輸出目錄，複核引數摘要，然後點選 Run protection。

2. CLI 示例

Manifest 已包含正確的 Main-Class 時：

p4j javaapp app.jar dist

Manifest 沒有 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 overlay、JavaFX 和歸檔字尾等選項。對後三類選項，命令列中顯式指定的值優先；建議的排除類則預設與顯式 --exclude 合併。如不希望自動追加排除類，可同時傳入 --no-compat-excludes。掃描器只做靜態啟發式分析，需要修改程式碼的問題不會被 --compat-apply 自動修復，生成後仍需在目標平臺迴歸測試。

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

3. 輸出結構

dist/
├── app.p4jx              # 或 --archive-suffix jar 生成 app.jar
├── vlxjre/               # 與歸檔和目標平臺匹配的執行時
├── lib/                  # Manifest Class-Path 依賴，可選
├── run.sh
├── run.command
├── run.bat
└── README.md

非 class 資源儲存在 P4JX 的公開資源檢視中。受保護 class 資源對掃描器只呈現後設資料樁；真實方法體只能由 VLX 執行時載入。

4. 啟動

./run.sh [應用引數...]

Windows：

run.bat [應用引數...]

不要用系統 JRE 替代輸出目錄中的 vlxjre。如果必須手工啟動，請以生成指令碼為模板保留其類路徑、VM 引數和 JavaFX模組引數。

JVM 啟動引數

打包時可在 GUI 的 JVM startup options 中每行填寫一個引數，或在 CLI 中重複使用：

--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。