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 启动选项配置。