JVM 启动参数配置

Protector4J 支持在打包时配置 JVM 启动参数，也支持在部署后临时追加或直接修改生成的启动脚本。GUI 中其他高级参数见 Protector4J 高级模式设置。

1. 三种配置方式

方式生效范围是否随重新打包保留推荐用途
GUI 的 JVM startup options写入本次生成的全部平台启动脚本是，任务参数仍在时可重复生成日常交互式打包
CLI 的 --jvm-option写入本次生成的全部平台启动脚本是，命令/任务脚本可作为配置源CI/CD、可重复发布
修改 run.sh、run.bat 或 Tomcat 脚本只修改当前部署目录否，重新打包会覆盖部署后的紧急或环境专属调整
APP_JAVA_OPTS 环境变量只影响当前进程或当前环境不写入文件临时诊断、容器/服务环境注入

推荐把长期参数放在 GUI 任务或 CLI 命令中，把 APP_JAVA_OPTS 用作临时覆盖。直接修改生成脚本后，应把改动记录到部署配置；下次重新打包需要重新应用。

2. 在 GUI 中配置

  1. 在输入页选择 Advanced — customise the options yourself；简单模式可在最终页点击 Customize… 进入高级参数。
  2. 在 Common options 中找到 JVM startup options。
  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 的启动路径。Library Encryption 只生成归档、不生成启动脚本，因此不提供此配置。

GUI 中的 JVM startup options

3. 在 CLI 中配置

每个参数使用一次 --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 和 batch 脚本分别转义。

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 命令之后。
  • 修改堆大小后应结合容器内存限制、操作系统可用内存和实际负载进行验证。
  • 重新打包会重写启动脚本，手工改动不会自动合并。