保护普通 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。