Tham chiếu dòng lệnh
Các ví dụ ở trang này dùng lệnh p4j có sẵn sau khi cài đặt. Trên Windows, giao diện đồ họa được cài từ tệp .exe; trên macOS thì từ Protector4J.app bên trong .dmg. Cách cài giao diện không làm thay đổi cú pháp dưới đây. Nếu trình cài đặt chưa đưa CLI vào PATH, hãy chạy nó từ lối vào dòng lệnh trong thư mục cài đặt Protector4J.
p4j --help
1. Các lệnh
p4j encode <input.jar> <output.p4jx|output.jar> [tùy chọn]
p4j javaapp <input.jar> <thư mục xuất> [tùy chọn]
p4j springboot <input.jar> <thư mục xuất> [tùy chọn]
p4j tomcat <input.war> <thư mục xuất> [tùy chọn]
Với lệnh cấp thấp encode, bạn có thể bỏ hẳn tên lệnh:
p4j input.jar output.p4jx [tùy chọn]
Các tùy chọn ở mức khởi chạy dùng để chọn đích đóng gói. Chúng có thể đặt trước tên lệnh, hoặc gom lại ở cuối dòng lệnh — dòng lệnh mà giao diện xuất ra dùng cách thứ hai.
| Tùy chọn | Mô tả |
|---|---|
--java-version <N> | Nhánh Java đi kèm: 8, 11, 17, 21 hoặc 25. Mặc định là 21 |
--target-platform <id>[,<id>...] | Một hoặc nhiều nền tảng mục tiêu, ngăn cách bằng dấu phẩy hoặc lặp lại tùy chọn. Mặc định là nền tảng hiện tại |
--create-new-folder | Tạo thư mục con p4jx-xxxxxxxx bên trong thư mục xuất. Chỉ áp dụng cho javaapp, springboot và tomcat |
Ví dụ:
p4j --java-version 21 --target-platform linux-x64 springboot app.jar dist
p4j springboot app.jar dist --java-version 21 --target-platform linux-x64
Hai lệnh này tương đương nhau. Không được chèn tùy chọn mức khởi chạy vào giữa các tùy chọn của trình đóng gói: ở đó chúng bị coi là tùy chọn lạ và lệnh sẽ báo lỗi.
2. Tùy chọn chung
| Tùy chọn | Mô tả |
|---|---|
--jre-home <path> | Suy ra khóa từ môi trường chạy P4JX cuối cùng được chỉ định. Các lệnh đóng gói cấp cao còn sao chép luôn môi trường chạy này |
--keys <keys.json> | Dùng tệp khóa riêng tường minh. Chỉ dành cho chẩn đoán và quy trình nội bộ; tuyệt đối không phát hành kèm ứng dụng |
--no-jit | Giữ các phương thức được bảo vệ ngoài JIT và chạy chúng trong trình thông dịch |
--zip-overlay off|scanner | Tắt hoặc bật khung nhìn tương thích ZIP cho trình quét. Mặc định là off |
--compat-scan | Chỉ quét rồi kết thúc; không cần tham số đầu ra |
--compat-apply | Quét, áp dụng các khuyến nghị an toàn rồi tiếp tục mã hóa |
--no-compat-excludes | Dùng kèm --compat-apply: không tự thêm các mục loại trừ được khuyến nghị |
--native-compat jxbrowser | Chỉ dành cho javaapp và springboot: xin cấp quyền cho JxBrowser tích hợp sẵn. Phiên bản, nền tảng và mã băm năm lớp vẫn được kiểm tra đầy đủ; không chấp nhận giá trị, đường dẫn hay mã băm nào khác |
--account-email <email> | Email của tài khoản có giấy phép |
--account-password <password> | Mật khẩu của tài khoản có giấy phép |
--app-id <id> | Định danh ứng dụng |
--license-expires-in <sec> | Thời hạn dùng thử yêu cầu, tính bằng giây, trong giới hạn chính sách của máy chủ |
Các lệnh đóng gói cấp cao còn hỗ trợ thêm:
| Tùy chọn | Mô tả |
|---|---|
--archive-suffix p4jx|jar | Hậu tố của kho lưu trữ được tạo, mặc định p4jx. Định dạng bên trong không đổi |
--jvm-option <option> | Ghi tùy chọn vào tập lệnh khởi chạy cho macOS, Linux và Windows. Mỗi tham số một tùy chọn, có thể lặp lại. Khi bật EXE cho Windows, cùng bộ tùy chọn đó cũng được nhúng vào EXE |
3. encode
p4j encode input.jar output.p4jx [tùy chọn]
| Tùy chọn | Mô tả |
|---|---|
--bind-launcher <jar> | Tính mã băm SHA-256 của JAR trình khởi chạy rồi gắn kết |
--launcher-sha256 <hex> | Truyền thẳng mã băm SHA-256 của trình khởi chạy, dành cho tích hợp nâng cao |
--runtime-major <N> | Đích cho khung nhìn tài nguyên và việc làm phẳng JAR đa phiên bản. Mặc định là 21 |
--bind-launcher và --launcher-sha256 không dùng chung được.
4. javaapp
p4j javaapp input.jar thư-mục-xuất [tùy chọn]
| Tùy chọn | Mô tả |
|---|---|
--main <class> | Lớp chính để khởi chạy |
--protect <rules> | Quy tắc cho các lớp và gói cần bảo vệ, ngăn cách bằng dấu phẩy. Mặc định là mọi lớp |
--exclude <rules> | Quy tắc cho những gì nằm ngoài phạm vi bảo vệ |
--javafx [<dir>] | Bật JavaFX, có thể kèm thư mục thành phần cục bộ |
--javafx-webview | Luôn đưa WebView vào |
--no-javafx-webview | Không bao giờ đưa WebView vào |
--no-javafx | Tắt hẳn JavaFX |
--native-compat jxbrowser | Ghi ATTACH_THREAD cho các thư viện IPC của JxBrowser khớp chính xác với thư mục tích hợp sẵn. Chỉ Java 17, 21 và 25 |
5. springboot
p4j springboot input.jar thư-mục-xuất [tùy chọn]
| Tùy chọn | Mô tả |
|---|---|
--main <class> | Lớp chính của Spring Boot. Mặc định đọc từ tệp kê khai |
--protect <rules> | Bảo vệ các lớp khớp mẫu trong BOOT-INF/classes |
--exclude <rules> | Để các lớp hoặc gói khớp mẫu không được bảo vệ |
--protect-lib <globs> | Bảo vệ các JAR khớp mẫu trong BOOT-INF/lib, ngăn cách bằng dấu phẩy |
--layout p4jx-fat|fat|separate | Bố trí đầu ra, mặc định p4jx-fat |
--javafx [<dir>] | Bật JavaFX, có thể kèm thư mục thành phần cục bộ |
--javafx-webview | Luôn đưa WebView vào |
--no-javafx-webview | Không bao giờ đưa WebView vào |
--no-javafx | Tắt hẳn JavaFX |
--native-compat jxbrowser | Giống javaapp; cùng một trình quét bao quát cả BOOT-INF/lib lồng bên trong |
6. tomcat
p4j tomcat input.war thư-mục-xuất [tùy chọn]
| Tùy chọn | Mô tả |
|---|---|
--exclude <rules> | Để các lớp hoặc gói khớp mẫu trong WEB-INF/classes không được bảo vệ |
--context </path> | Đường dẫn ngữ cảnh, mặc định /app |
--append-app | Thêm ứng dụng vào một gói Tomcat P4JX sẵn có |
--tomcat-version auto|9|10 | Tự phát hiện hoặc ấn định phiên bản. Trên dòng lệnh mặc định là auto |
--precompile-jsp | Buộc biên dịch trước JSP |
--no-precompile-jsp | Tắt việc biên dịch trước JSP |
7. Tùy chọn EXE cho Windows
javaapp, springboot và tomcat có thể tạo thêm một trình khởi chạy Windows gốc. Danh sách nền tảng mục tiêu phải có windows-x64, windows-x86 hoặc windows-aarch64.
| Tùy chọn | Mô tả |
|---|---|
--windows-exe | Tạo EXE ứng dụng Windows. Không truyền thì không tạo |
--exe-name <name> | Tên tệp EXE; mặc định lấy tên tệp đầu vào, gói tomcat dùng tomcat |
--exe-mode <mode> | console (mặc định) hoặc gui |
--exe-icon <ico> | Biểu tượng Windows không bắt buộc, định dạng .ico |
--exe-file-version <a.b.c.d> | Phiên bản tệp PE: từ một đến bốn số, mỗi số từ 0 đến 65535. Để trống nghĩa là 0.0.0.0 |
--exe-product-version <a.b.c.d> | Phiên bản sản phẩm PE, quy tắc tương tự |
--exe-company <text> | Tên công ty |
--exe-product <text> | Tên sản phẩm |
--exe-description <text> | Mô tả tệp |
--exe-copyright <text> | Thông báo bản quyền |
Bất kỳ tùy chọn --exe-* nào cũng tự bật việc tạo EXE. Trong tác vụ nhiều nền tảng, chỉ gói Windows mới có EXE; các nền tảng khác vẫn được tạo bình thường và giữ nguyên tập lệnh khởi chạy.
p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe --exe-name MyApp.exe --exe-mode gui
Hướng dẫn đầy đủ, hành vi lúc chạy và các bước ký mã nằm ở Tạo trình khởi chạy EXE Windows.
8. Cách viết quy tắc
com.example.SecretService một lớp duy nhất
com.example.service chỉ gói này
com.example.service.* chỉ gói này
com.example.service.** gói này và mọi gói con
com/example/Secret.class đường dẫn của một mục lớp
Nhiều quy tắc thì ngăn cách bằng dấu phẩy. Quy tắc có * nên đặt trong dấu nháy để shell không tự khai triển:
--protect 'com.example.**' --exclude 'com.example.dto.**,com.example.config.**'
9. Biến môi trường
Biến môi trường hợp với việc đặt giá trị mặc định dùng chung cho một tác vụ CI, một vùng chứa, hoặc nhiều lệnh chạy liên tiếp. Khi cần ghi nhận và tái lập chính xác một lượt đóng gói cụ thể, hãy truyền giá trị tường minh bằng tùy chọn dòng lệnh.
| Biến | Tùy chọn tương ứng | Mô tả |
|---|---|---|
P4JX_RUNTIME_JAVA_VERSION | --java-version <N> | Nhánh Java dùng cho đóng gói cấp cao: 8, 11, 17, 21 hoặc 25 |
P4JX_RUNTIME_PLATFORM | --target-platform <id> | Một nền tảng mục tiêu duy nhất. Muốn đóng gói nhiều nền tảng cùng lúc thì dùng tùy chọn dòng lệnh |
P4JX_RUNTIME_CACHE_DIR | không có | Thay thế thư mục bộ đệm tải VLX JRE |
APP_JAVA_OPTS | so với --jvm-option | Thêm tùy chọn JVM cho một lần chạy ứng dụng đã tạo. --jvm-option ghi tùy chọn vào tập lệnh ngay lúc đóng gói, nên hai thứ này không tương đương |
Nếu vừa đặt biến vừa truyền tùy chọn tương ứng, tùy chọn tường minh sẽ thắng. Các biến môi trường vẫn được hỗ trợ đầy đủ nên tập lệnh tự động hóa hiện có của bạn tiếp tục chạy bình thường.
Ví dụ, đặt một đích chung cho nhiều lệnh đóng gói trong shell hiện tại:
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
Với các trường hợp nâng cao khi bạn chạy thẳng tệp JAR của trình đóng gói, có các thuộc tính hệ thống Java tương đương:
-Dp4jx.runtime.java.version=<N>
-Dp4jx.runtime.platform=<platform>
-Dp4jx.runtime.cache.dir=<dir>
10. Ví dụ tự động hóa
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
Các tùy chọn bảo vệ, loại trừ và bố trí được chỉ định tường minh sẽ ghi đè khuyến nghị tự động. Bạn nên ghi lại bộ tùy chọn cuối cùng, mã băm SHA-256 của tệp đầu vào và phiên bản công cụ để làm chứng cứ nguồn gốc cho bản phát hành.
Ví dụ cho giao diện và dòng lệnh, cùng cách sửa run.sh, run.bat, tập lệnh khởi chạy Tomcat và PowerShell, nằm ở Tùy chọn khởi chạy JVM.