Tạo trình khởi động dạng Windows EXE

Khi đóng gói, có thể tạo một trình khởi động nguyên bản dành cho ứng dụng được bảo vệ. Đây là tệp thực thi thuần Win32, người dùng chỉ cần nhấp đúp để chạy ứng dụng mà không cần cài đặt Java trước, cũng không cần phải thấy run.bat.

EXE là tùy chọn và mặc định sẽ không được tạo ra. Khi bật tính năng này, các tệp run.sh / run.command / run.bat ban đầu vẫn được giữ nguyên trong gói đóng gói; cả hai phương thức khởi động đều sử dụng chung các thông số về file nén, classpath, lớp chính và tham số JVM.

1. Phạm vi bảo vệ

Phải chọn ít nhất một nền tảng mục tiêu là Windows. Việc chọn đồng thời các nền tảng Linux hoặc macOS sẽ không khiến nhiệm vụ thất bại: các gói con dành cho những nền tảng này vẫn được tạo ra như bình thường, chỉ là không có tệp EXE và vẫn sử dụng script khởi động ban đầu. Nếu tất cả các nền tảng mục tiêu đều không phải là Windows, nhiệm vụ sẽ ngay lập tức báo lỗi.

2. Thao tác qua giao diện người dùng

1. Trên trang chọn tệp đầu vào và nền tảng mục tiêu, hãy đánh dấu ô Tạo tập tin EXE cho ứng dụng Windows (x64/x86/ARM64) và chọn ít nhất một nền tảng mục tiêu là Windows.
2. Nút tùy chọn này nằm trước điểm chia giữa chế độ đơn giản và chế độ nâng cao, vì vậy cả hai chế độ đều có thể tạo ra tệp EXE.
3. Khi đánh dấu, một trang Trình khởi động Windows EXE mới sẽ xuất hiện để điền tên tệp, chế độ trình khởi động, biểu tượng và thông tin phiên bản Windows. Nếu không đánh dấu, người dùng sẽ được chuyển thẳng đến trang xác nhận cuối cùng.
4. Khi kích hoạt EXE, ô nhập Các tham số khởi động JVM chỉ xuất hiện trên trang khởi động này nhằm tránh tình trạng một tham số có hai lối truy cập. Các tham số được nhập sẽ được ghi vào cả tệp EXE lẫn script khởi động.
5. Trang xác nhận cuối cùng sẽ liệt kê các nền tảng thực sự sẽ tạo ra EXE, cùng với các trường thông tin khởi động đã được điền.

3. Ví dụ CLI

Dạng đơn giản nhất, chỉ cần --windows-exe:

p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe

Chỉ định tên tệp và chế độ cửa sổ:

p4j --target-platform windows-x64 javaapp app.jar dist \
  --windows-exe \
  --exe-name MyApp.exe \
  --exe-mode gui \
  --exe-icon assets/app.ico

Tạo ra cùng lúc ba kiến trúc Windows và điền đầy đủ các tài nguyên phiên bản:

p4j --target-platform windows-x64,windows-x86,windows-aarch64 \
  springboot app.jar dist \
  --windows-exe \
  --exe-name MyService \
  --exe-file-version 1.4.2.0 \
  --exe-product-version 1.4.2.0 \
  --exe-company 'Example Inc.' \
  --exe-product 'Example Service' \
  --exe-description 'Example background service' \
  --exe-copyright 'Copyright (C) 2026 Example Inc.'

Gói Tomcat cũng được hỗ trợ; tệp EXE tạo ra sẽ khởi động Tomcat tích hợp ở chế độ nền:

p4j --target-platform windows-x64 tomcat app.war dist --context /demo --windows-exe

4. Giải thích các tham số

Bất kỳ tùy chọn nào của --exe-* cũng sẽ tự động kích hoạt việc tạo tệp EXE, không cần phải viết thêm --windows-exe nữa.

Tên tệp chỉ có thể là tên tệp thuần, không được chứa /, \ hay phần thư mục; nếu không có hậu tố .exe thì sẽ được tự động bổ sung.

Quy tắc cho cả hai trường mã phiên bản đều giống nhau: các số từ 1 đến 4 được tách bằng dấu chấm phẩy, mỗi số nằm trong khoảng từ 0 đến 65535, ví dụ như 1.0.0.1. Windows lưu mỗi số thành một số nguyên không dấu 16 bit, vì vậy sẽ không chấp nhận các dạng có chứa chữ cái hoặc dấu cách như v1.0, 1.0-beta. Việc để trống có nghĩa là 0.0.0.0. Hai trường này sẽ được kiểm tra trước khi bắt đầu quá trình đóng gói, và sẽ không gây lỗi cho đến khi quá trình đang diễn ra.

5. Cấu trúc đầu ra

Lấy Java Application làm ví dụ, tệp EXE và script khởi động được đặt cùng nhau trong thư mục gốc của gói:

dist/
├── MyApp.exe             # Trình khởi động Windows mới được thêm vào
├── app.p4jx
├── vlxjre/
├── lib/
├── run.sh
├── run.command
├── run.bat
└── README.md

Tệp README.md bên trong gói sẽ liệt kê tên tệp EXE được tạo ra kèm theo thông báo về chữ ký mã nguồn.

6. Hành vi khi chạy

Thư mục chứa tệp EXE chính là thư mục gốc của ứng dụng. Trình khởi động chỉ chấp nhận các thư mục runtime, archive, classpath và working directory nằm bên trong thư mục gốc; các đường dẫn chỉ ra ngoài thư mục gói, cũng như các đường dẫn đã được thay thế bằng liên kết tượng trưng hoặc junction point đều sẽ bị từ chối và quá trình sẽ không được khởi động. Điều này có nghĩa là người dùng có thể di chuyển hoặc đổi tên toàn bộ gói, nhưng không thể sao chép tệp EXE ra riêng để sử dụng.

Các tham số JVM của EXE sẽ được cố định ngay khi đóng gói và ký kèm theo khối tham số; chúng sẽ được kiểm tra khi chạy và không thể được sửa đổi sau khi triển khai. APP_JAVA_OPTS chỉ có hiệu lực với run.bat mà thôi, và EXE sẽ không đọc nó. Nếu cần thay đổi các tham số JVM của EXE, hãy tiến hành đóng gói lại.

Vì lý do tương tự, các tệp -javaagent, -agentlib, -agentpath, -Xbootclasspath và --patch-module cũng không cho phép ghi thêm các tham số khởi động vào EXE. Khi cố gắng truyền những tham số này bằng --jvm-option, quá trình đóng gói sẽ thất bại ngay lập tức.

7. Ký kết mã nguồn

Protector4J không thêm chữ ký nhà phát hành vào EXE được tạo ra, cũng không tiếp cận bất kỳ thông tin xác thực Authenticode nào. Tất cả các thay đổi liên quan đến cấu trúc PE như hình ảnh biểu tượng, tài nguyên phiên bản và tham số khởi động đều được thực hiện trong giai đoạn đóng gói; vì vậy bước ký kết nên được thực hiện ở cuối cùng.

1. Hoàn tất việc đóng gói và kiểm tra xem EXE có thể khởi động ứng dụng một cách bình thường hay không.
2. Sử dụng chứng chỉ riêng của bạn để thực hiện ký kết Authenticode, đồng thời thêm dấu thời gian RFC3161.
3. Sử dụng chính sách /pa của Windows để kiểm tra chữ ký.

Sau khi ký kết xong, đừng sửa đổi tập tin PE này nữa; bất kỳ thay đổi nào cũng sẽ làm mất hiệu lực chữ ký. Khi cần thay đổi biểu tượng hoặc số phiên bản, vui lòng đóng gói lại và ký kết mới.

8. Trường tập tin nhiệm vụ

p4j-task.yml được xuất ra sử dụng phiên bản 2; khi kích hoạt EXE, hãy lưu các trường sau. Các tập tin nhiệm vụ phiên bản 1 vẫn có thể được đọc bình thường.

windowsExe: true
exeName: MyApp.exe
exeMode: console
exeIcon: assets/app.ico
exeFileVersion: 1.4.2.0
exeProductVersion: 1.4.2.0
exeCompany: Example Inc.
exeProduct: Example Service
exeDescription: Example background service
exeCopyright: Copyright (C) 2026 Example Inc.

9. Các câu hỏi thường gặp

Các tùy chọn CLI đầy đủ có thể được xem tại Tham khảo tham số CLI, còn quy trình hướng dẫn GUI thì nằm ở Hướng dẫn sử dụng GUI.