CLI 參數參考
本文的範例使用安裝後提供的 p4j 命令。Windows 的 GUI 由 .exe 安裝，macOS 的 GUI 由 .dmg 中的 Protector4J.app 安裝；GUI 的安裝方式不會改變下面的 CLI 語法。如果安裝程式沒有把 CLI 加入 PATH，請從 Protector4J 安裝目錄中的命令列入口執行。
p4j --help
1. 命令
p4j encode <input.jar> <output.p4jx|output.jar> [選項]
p4j javaapp <input.jar> <輸出目錄> [選項]
p4j springboot <input.jar> <輸出目錄> [選項]
p4j tomcat <input.war> <輸出目錄> [選項]
底層的 encode 還允許省略命令名稱：
p4j input.jar output.p4jx [選項]
啟動層級的選項用於選擇打包目標。它們可以寫在命令名稱之前，也可以作為整條命令末端的連續字尾 —— GUI 匯出的命令列採用的就是字尾寫法。
| 選項 | 說明 |
|---|---|
--java-version <N> | 隨包的 Java 訓練線：8、11、17、21 或 25，預設 21 |
--target-platform <id>[,<id>...] | 一個或多個目標平臺，以逗號分隔或重複使用該選項。預設為目前平臺。 |
--create-new-folder | 在輸出目錄中新建一個 p4jx-xxxxxxxx 子目錄。僅適用於 javaapp、springboot 與 tomcat。 |
例如：
p4j --java-version 21 --target-platform linux-x64 springboot app.jar dist
p4j springboot app.jar dist --java-version 21 --target-platform linux-x64
這兩條命令等價。啟動層級的選項不能夾在打包器選項中間，否則會被當成未知的打包器選項而報錯。
2. 通用選項
| 選項 | 說明 |
|---|---|
--jre-home <path> | 以指定的 P4JX 最終 JRE 執行時衍生金鑰；高層打包命令還會複製該執行時 |
--keys <keys.json> | 使用私有的明確金鑰檔案。僅限診斷與內部流程使用，絕不能隨應用程式散布。 |
--no-jit | 讓受保護方法不進入 JIT，改為解譯器執行 |
--zip-overlay off|scanner | 關閉或啟用掃描器 ZIP 相容檢視，預設 off |
--compat-scan | 只掃描後結束，不需要輸出參數 |
--compat-apply | 掃描、套用保守建議，然後繼續編碼 |
--no-compat-excludes | 搭配 --compat-apply 使用：不自動追加建議的排除類別 |
--native-compat jxbrowser | 僅適用於 javaapp 與 springboot：為內建的 JxBrowser 申請准入。版本、平臺與五層雜湊仍會完整驗證，不接受其他值、路徑或雜湊。 |
--account-email <email> | 授權帳號電子郵件 |
--account-password <password> | 授權帳號密碼 |
--app-id <id> | 應用程式識別碼 |
--license-expires-in <sec> | 要求的試用有效秒數，受伺服器政策約束 |
高層打包命令另外支援：
| 選項 | 說明 |
|---|---|
--archive-suffix p4jx|jar | 產生歸檔的檔案字尾，預設 p4jx；不改變內部格式 |
--jvm-option <option> | 寫入 macOS、Linux 與 Windows 的啟動指令碼。每個選項用一次，可重複使用。啟用 Windows EXE 時，同一組選項也會固化進 EXE。 |
3. encode
p4j encode input.jar output.p4jx [選項]
| 選項 | 說明 |
|---|---|
--bind-launcher <jar> | 計算並繫結啟動器 JAR 的 SHA-256 |
--launcher-sha256 <hex> | 直接傳入啟動器的 SHA-256，供進階整合使用 |
--runtime-major <N> | 資源檢視與 Multi-Release 攤平的目標版本，預設 21 |
--bind-launcher 與 --launcher-sha256 不能同時使用。
4. javaapp
p4j javaapp input.jar 輸出目錄 [選項]
| 選項 | 說明 |
|---|---|
--main <class> | 指定啟動的主類 |
--protect <rules> | 要保護的類別與套件規則，以逗號分隔。預設保護全部類別。 |
--exclude <rules> | 要從保護範圍中排除的規則 |
--javafx [<dir>] | 啟用 JavaFX，可選指定本機元件目錄 |
--javafx-webview | 強制納入 WebView |
--no-javafx-webview | 強制排除 WebView |
--no-javafx | 明確停用 JavaFX |
--native-compat jxbrowser | 為完整命中內建目錄的 JxBrowser IPC 函式庫寫入 ATTACH_THREAD。僅支援 Java 17、21、25。 |
5. springboot
p4j springboot input.jar 輸出目錄 [選項]
| 選項 | 說明 |
|---|---|
--main <class> | 指定 Spring Boot 主類，預設從資訊清單讀取 |
--protect <rules> | 保護 BOOT-INF/classes 中相符的類別 |
--exclude <rules> | 排除相符的類別或套件 |
--protect-lib <globs> | 保護 BOOT-INF/lib 中相符的 JAR，以逗號分隔 |
--layout p4jx-fat|fat|separate | 輸出佈局，預設 p4jx-fat |
--javafx [<dir>] | 啟用 JavaFX，可選指定本機元件目錄 |
--javafx-webview | 強制納入 WebView |
--no-javafx-webview | 強制排除 WebView |
--no-javafx | 明確停用 JavaFX |
--native-compat jxbrowser | 與 javaapp 相同；巢狀的 BOOT-INF/lib 由同一個掃描器涵蓋。 |
6. tomcat
p4j tomcat input.war 輸出目錄 [選項]
| 選項 | 說明 |
|---|---|
--exclude <rules> | 排除 WEB-INF/classes 中相符的類別或套件 |
--context </path> | 上下文路徑，預設 /app |
--append-app | 把應用程式追加到既有的 P4JX Tomcat 包中 |
--tomcat-version auto|9|10 | 自動偵測或強制指定版本。CLI 預設為 auto。 |
--precompile-jsp | 強制預先編譯 JSP |
--no-precompile-jsp | 關閉 JSP 預先編譯 |
7. Windows EXE 選項
javaapp、springboot 與 tomcat 可以額外產生一個原生 Windows 啟動程式，要求目標平臺中包含 windows-x64、windows-x86 或 windows-aarch64。
| 選項 | 說明 |
|---|---|
--windows-exe | 產生 Windows 應用程式 EXE。不傳入則不產生。 |
--exe-name <name> | EXE 檔案名稱；留空時使用輸入檔案的名稱，tomcat 包使用 tomcat |
--exe-mode <mode> | console（預設）或 gui |
--exe-icon <ico> | 選用的 Windows 圖示，.ico 格式 |
--exe-file-version <a.b.c.d> | PE 檔案版本：1 到 4 段數字，每段取值 0 到 65535。留空表示 0.0.0.0。 |
--exe-product-version <a.b.c.d> | PE 產品版本，規則同上 |
--exe-company <text> | 公司名稱 |
--exe-product <text> | 產品名稱 |
--exe-description <text> | 檔案說明 |
--exe-copyright <text> | 版權聲明 |
任何一個 --exe-* 選項都會自動啟用 EXE 產生。多平臺任務只會在 Windows 子包中產生 EXE，其他平臺的子包照常產生並保留啟動指令碼。
p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe --exe-name MyApp.exe --exe-mode gui
完整說明、執行行為與程式碼簽章步驟，請見產生 Windows EXE 啟動器。
8. 規則寫法
com.example.SecretService 單一類別
com.example.service 只比對目前套件
com.example.service.* 只比對目前套件
com.example.service.** 目前套件及其所有子套件
com/example/Secret.class 類別項目路徑
多條規則以逗號分隔。規則中含 * 時要加上引號，避免被 shell 展開：
--protect 'com.example.**' --exclude 'com.example.dto.**,com.example.config.**'
9. 環境變數
環境變數適合為 CI 工作、容器，或連續執行的多條命令設定共用的預設值。當某一次打包需要被記錄與重現時，還是應當把值當作 CLI 選項明確寫出來。
| 環境變數 | 對應的 CLI 選項 | 說明 |
|---|---|---|
P4JX_RUNTIME_JAVA_VERSION | --java-version <N> | 高層打包使用的 Java 訓練線：8、11、17、21 或 25 |
P4JX_RUNTIME_PLATFORM | --target-platform <id> | 單一目標平臺。一次打包多個平臺時請使用 CLI 選項。 |
P4JX_RUNTIME_CACHE_DIR | 無 | 覆寫 VLX JRE 的下載快取目錄 |
APP_JAVA_OPTS | 可對照 --jvm-option | 執行產生的應用程式時臨時追加 JVM 選項。--jvm-option 是在打包時把選項寫進啟動指令碼，兩者並不等價。 |
同時設定了環境變數與對應的 CLI 選項時，明確的 CLI 選項優先。環境變數仍然完整支援，既有的自動化指令碼可以繼續使用。
例如，在目前的 shell 中為後續多條打包命令設定共用目標：
export P4JX_RUNTIME_JAVA_VERSION=21
export P4JX_RUNTIME_PLATFORM=linux-x64
p4j springboot service-a.jar release/service-a
p4j springboot service-b.jar release/service-b
如果你是直接啟動打包器 JAR 的進階用法，可以改用等價的 Java 系統屬性：
-Dp4jx.runtime.java.version=<N>
-Dp4jx.runtime.platform=<platform>
-Dp4jx.runtime.cache.dir=<dir>
10. 自動化範例
p4j --java-version 21 \
--target-platform linux-x64 \
springboot build/app.jar release/linux-x64 \
--compat-apply \
--protect 'com.example.service.impl.**' \
--exclude 'com.example.dto.**,com.example.config.**' \
--jvm-option -Xms1g \
--jvm-option -Xmx2g \
--app-id com.example.app
明確指定的保護、排除與佈局選項會覆寫自動建議。建議把最終參數、輸入檔案的 SHA-256 與工具版本一併記錄為發行溯源資訊。
GUI 與 CLI 的範例，以及直接編輯 run.sh、run.bat、Tomcat 啟動指令碼與 Windows PowerShell 的寫法，請見 JVM 啟動選項設定。