JVM 啟動選項設定

Protector4J 支援在打包時設定 JVM 啟動選項，也支援在部署後臨時追加，或直接修改產生的啟動指令碼。GUI 中其他進階選項的說明請見 Protector4J 進階模式設定。

1. 四種設定方式

方式生效範圍重新打包後是否保留適用情境
GUI 的 JVM 啟動選項寫入本次產生的全部平臺啟動指令碼是，只要還留著任務參數就能重新產生日常互動式打包
命令列的 --jvm-option寫入本次產生的全部平臺啟動指令碼是，命令或任務檔案即設定來源CI/CD、可重複建置
修改 run.sh、run.bat 或 Tomcat 指令碼只影響你改動的那個部署目錄否，重新打包會覆寫部署後的緊急調整或環境專屬調整
APP_JAVA_OPTS 環境變數只影響目前的行程或環境不寫入任何檔案臨時診斷，以及從容器或服務環境注入

建議把長期使用的選項放在 GUI 任務或 CLI 命令中，把 APP_JAVA_OPTS 當作臨時覆寫。如果直接改了產生的指令碼，請把改動記錄到部署文件 —— 下次重新打包時必須再改一次。

2. 在 GUI 中設定

  1. 在輸入頁選擇高階——自行定製選項；從簡單模式進入時，在最終頁點選**自定義…**即可開啟進階選項。
  2. 在通用選項中找到 JVM 啟動選項。
  3. 每行填寫一個完整的選項，例如：
-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8
-Dspring.profiles.active=prod
  1. 在最終參數摘要中核對，然後執行保護。

這些選項會寫入產生的 run.sh 與 run.bat；macOS 的 run.command 呼叫的是同一份 run.sh，因此使用相同的選項。對 Tomcat，它們還會寫入 bin/catalina.sh 與 bin/catalina.bat 的啟動路徑。類庫加密只產生歸檔、不產生啟動指令碼，因此該輸入欄位無法使用。

GUI 中的 JVM 啟動選項

3. 在命令列中設定

每個選項重複使用一次 --jvm-option，不要把多個 JVM 選項塞進同一個值裡。

p4j javaapp app.jar dist \
  --jvm-option -Xms512m \
  --jvm-option -Xmx2g \
  --jvm-option -Dfile.encoding=UTF-8

Spring Boot：

p4j springboot app.jar dist \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

Tomcat：

p4j tomcat app.war dist \
  --context /app \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

單一選項如果包含空格或特殊字元，要整體加上引號：

--jvm-option '-Dexample.message=hello world'

打包器會依這些邊界，分別為 shell 指令碼與批次檔做逸出處理。

4. macOS 與 Linux：直接改指令碼

一般 Java 應用程式與 Spring Boot 應用程式，編輯輸出目錄中的 run.sh 即可。run.command 只是轉呼叫 run.sh，不需要另外修改。

找到產生的 JVM_OPTS=(...) 以及其後可能存在的 JVM_OPTS+=(...)，在 APP_JAVA_OPTS 判斷之前加上自己的一行：

JVM_OPTS+=("-Xms512m" "-Xmx2g" "-Dfile.encoding=UTF-8")
if [ -n "${APP_JAVA_OPTS:-}" ]; then
  # ...
fi

不要刪除打包器為 Spring Boot 或 JavaFX 產生的 --add-opens、--module-path 與 --add-modules。

Tomcat 則編輯 bin/catalina.sh，在 run_java() 內的 JVM_OPTS=(...) 之後加上自己的一行：

run_java() {
  JVM_OPTS=(...)
  JVM_OPTS+=("-Xms1g" "-Xmx2g")
  # ...
}

這樣的改動對 run.sh 的前景執行與 bin/startup.sh 的背景啟動都會生效。

5. Windows：直接改指令碼

一般 Java 應用程式與 Spring Boot 應用程式，編輯輸出目錄中的 run.bat。找到產生的 set "JVM_OPTS=..."，在 APP_JAVA_OPTS 判斷之前加上自己的一行：

set "JVM_OPTS=%JVM_OPTS% -Xms512m -Xmx2g -Dfile.encoding=UTF-8"
if defined APP_JAVA_OPTS set "JVM_OPTS=%JVM_OPTS% %APP_JAVA_OPTS%"

保留 JVM_OPTS 中原有的內容，不要刪除 Spring Boot 或 JavaFX 需要的內部選項。

Windows 上前景執行的 Tomcat

編輯 bin\catalina.bat，在既有的 set "JVM_OPTS=..." 之後加上：

set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g"

這對 run.bat 與 bin\catalina.bat run 都會生效。

Windows 上背景啟動的 Tomcat

bin\startup.bat 透過 PowerShell 建立背景行程。要做永久修改，最簡單的辦法是在它呼叫 catalina.bat 之前設定 APP_JAVA_OPTS：

@echo off
set "APP_JAVA_OPTS=-Xms1g -Xmx2g"
call "%~dp0catalina.bat" start %*
exit /b %ERRORLEVEL%

如果希望一次涵蓋前景與背景，又不想維護兩處指令碼，比較省事的做法是用 GUI 或 CLI 加上 --jvm-option 重新產生 Tomcat 包。

6. 用 APP_JAVA_OPTS 臨時生效

macOS 與 Linux

APP_JAVA_OPTS="-Xms512m -Xmx2g" ./run.sh

Tomcat：

APP_JAVA_OPTS="-Xms1g -Xmx2g" ./bin/startup.sh

Windows CMD

在目前的 CMD 工作階段中設定，後續命令都會繼承；用 set APP_JAVA_OPTS= 清除：

set "APP_JAVA_OPTS=-Xms512m -Xmx2g"
run.bat

如果希望只在區域生效、執行完自動還原環境：

setlocal
set "APP_JAVA_OPTS=-Xms512m -Xmx2g"
call run.bat
endlocal

Tomcat：

set "APP_JAVA_OPTS=-Xms1g -Xmx2g"
bin\startup.bat

Windows PowerShell

$env:APP_JAVA_OPTS = '-Xms512m -Xmx2g'
.\run.bat
Remove-Item Env:APP_JAVA_OPTS

7. 順序與注意事項

  • 工具產生的選項排在最前，其次是你在 GUI 或 CLI 中設定的選項，APP_JAVA_OPTS 追加在最後。
  • 部分 JVM 選項後出現的值會覆寫先出現的值，但並非所有選項都允許重複出現，不要依賴重複來做覆寫。
  • APP_JAVA_OPTS 以空格切分，因此無法承載本身含空格的單一選項；這類選項請用 GUI、--jvm-option，或直接編輯指令碼中的陣列。
  • JVM 選項必須放在主類或 -jar 之前；應用程式自身的參數放在 run.sh 或 run.bat 命令之後。
  • 調整堆積大小之後，要結合容器記憶體限制、主機可用記憶體與實際負載一起驗證。
  • 重新打包會覆寫啟動指令碼，手動改動不會被自動合併回來。