Tạo trình khởi chạy EXE Windows

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

EXE là tùy chọn và chỉ được tạo khi bạn yêu cầu. Khi bật, gói vẫn giữ nguyên run.sh, run.command và run.bat. Cả hai cách khởi chạy đều dùng chung cấu trúc kho lưu trữ, classpath, lớp chính và tùy chọn khởi chạy JVM.

1. Phạm vi áp dụng

Bạn phải chọn ít nhất một nền tảng mục tiêu Windows. Chọn kèm cả Linux và macOS thì không sao: gói của những nền tảng đó vẫn được tạo bình thường, chỉ là không có EXE và khởi chạy bằng tập lệnh như cũ. Nếu không chọn nền tảng Windows nào, tác vụ sẽ báo lỗi ngay.

2. Thao tác trên giao diện đồ họa

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

3. Ví dụ dòng lệnh

Dạng tối giản 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 cả ba kiến trúc Windows cùng lúc kèm tài nguyên phiên bản đầy đủ:

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 dùng được; EXE tạo ra sẽ chạy Tomcat nhúng ở tiền cảnh:

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

4. Các tùy chọn

Bất kỳ tùy chọn --exe-* nào cũng tự bật việc tạo EXE, nên không cần thêm --windows-exe.

Tên phải là tên tệp thuần túy, không chứa /, \ hay thành phần thư mục. Nếu bạn bỏ hậu tố .exe, nó sẽ được thêm tự động.

Hai trường phiên bản theo cùng một quy tắc: từ một đến bốn số ngăn cách bằng dấu chấm, mỗi số từ 0 đến 65535, ví dụ 1.0.0.1. Windows lưu mỗi phần dưới dạng số nguyên không dấu 16 bit, nên những giá trị chứa chữ cái hay khoảng trắng như v1.0 hay 1.0-beta sẽ bị từ chối. Trường để trống nghĩa là 0.0.0.0. Cả hai trường được kiểm tra trước khi bắt đầu đóng gói, nên sai sót lộ ra ngay chứ không phải giữa chừng.

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

Lấy ứng dụng Java làm ví dụ, EXE nằm ở gốc gói, cạnh các tập lệnh khởi chạy:

dist/
├── MyApp.exe             # trình khởi chạy Windows mới thêm
├── app.p4jx
├── vlxjre/
├── lib/
├── run.sh
├── run.command
├── run.bat
└── README.md

Tệp README.md trong gói liệt kê các EXE đã tạo cùng những lưu ý về ký mã.

6. Cách trình khởi chạy hoạt động

Thư mục chứa EXE chính là gốc của ứng dụng. Trình khởi chạy chỉ chấp nhận đường dẫn tới môi trường chạy, kho lưu trữ, classpath và thư mục làm việc nằm trong gốc đó; mọi thứ bên ngoài gói, cũng như mọi thứ bị thay thế bằng liên kết tượng trưng hay junction, đều bị từ chối và tiến trình sẽ không khởi động. Nhờ vậy bạn có thể di chuyển hay đổi tên cả gói tùy ý, nhưng không thể chép riêng tệp EXE ra chỗ khác.

Tùy chọn JVM của EXE được cố định lúc đóng gói, ký cùng khối tham số và kiểm tra lúc chạy; sau khi triển khai thì không đổi được nữa. APP_JAVA_OPTS chỉ tác động tới run.bat — EXE không đọc nó. Muốn đổi tùy chọn JVM của EXE, hãy đóng gói lại.

Cũng vì lý do đó, -javaagent, -agentlib, -agentpath, -Xbootclasspath và --patch-module không thể ghi vào tùy chọn khởi chạy của EXE. Truyền chúng qua --jvm-option sẽ khiến lượt đóng gói hỏng ngay lập tức.

7. Ký mã

Protector4J không ký tệp EXE tạo ra và cũng không đụng tới bất kỳ thông tin xác thực Authenticode nào. Mọi chỉnh sửa PE — biểu tượng, tài nguyên phiên bản, tùy chọn khởi chạy — đều hoàn tất trong lúc đóng gói, nên việc ký phải làm sau cùng.

1. Hoàn tất đóng gói và xác nhận EXE khởi chạy ứng dụng đúng cách.
2. Ký Authenticode bằng chứng chỉ của riêng bạn, kèm dấu thời gian RFC3161.
3. Xác minh chữ ký theo chính sách /pa của Windows.

Sau khi ký, đừng sửa tệp PE nữa: mọi thay đổi đều làm chữ ký mất hiệu lực. Muốn đổi biểu tượng hay số phiên bản, hãy đóng gói lại rồi ký lại.

8. Các trường trong tệp tác vụ

Tệp p4j-task.yml xuất ra dùng định dạng phiên bản 2 và lưu các trường sau khi EXE được bật. Tệp tác vụ phiên bản 1 vẫn đọc được.

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. Xử lý sự cố

Danh sách tùy chọn đầy đủ nằm trong Tham chiếu dòng lệnh; còn trình hướng dẫn đồ họa được mô tả ở Hướng dẫn giao diện đồ họa.