# JavaFX + jpackage 打包 macOS `.app` 完整流程 ## 一、準備工具與下載 **使用設備 MacBook Air M3 15inch** | 名稱 | 用途 | 建議下載位置(直接存於Downloads即可) | |------|------|---------------| | JavaFX SDK (`javafx-sdk-21.0.7`) | 執行 JavaFX 程式用 | `/Users/使用者/Downloads/` | | JavaFX JMODS (`javafx-jmods-21.0.7`) | 提供 jlink 模組 | `/Users/使用者/Downloads/` | | JDK 21（Temurin） | jlink / jpackage 必備 | `/Library/Java/JavaVirtualMachines/temurin-21.jdk` | ![CleanShot 2025-05-31 at 18.10.50](https://hackmd.io/_uploads/BJ32HU_zel.jpg) > JavaFX 下載(SDK和jmods)：https://gluonhq.com/products/javafx/ > JDK 下載：https://adoptium.net/ --- ## 二、Maven 專案結構 ``` mavenproject2/ ├── src/ │ └── main/ │ ├── java/ │ │ └── FinalProject/ │ │ ├── Run.java ← 主類別（入口） │ │ └── 其他 .java 檔 │ └── resources/ │ └── lobby_logo.png ← 圖片放這裡 ├── pom.xml ``` --- ## 三、使用 Maven 編譯 Jar Maven 需自行下載安裝 ```bash cd /Users/使用者/Desktop/mavenproject2 ``` ```bash mvn clean package ``` > 成果位置：`target/mavenproject2-1.0-SNAPSHOT.jar` --- ## 四、使用 jlink 建立 JavaFX Runtime 環境 MacOS ```bash /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/jlink \ --module-path "/Users/使用者/Downloads/javafx-jmods-21.0.7:/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/jmods" \ --add-modules javafx.controls,javafx.fxml \ --output javafx-jre ``` > 成果位置：`javafx-jre/`（含 JavaFX 的專屬 runtime） Windows PowerShell ```bash jlink ` --module-path "C:\Users\使用者\Downloads\javafx-jmods-21.0.7;C:\Program Files\Eclipse Adoptium\jdk-21\jmods" ` --add-modules javafx.controls,javafx.fxml ` --output javafx-jre ``` --- ## 五、使用 jpackage 打包為 `.app`或是 `.exe` 請自行替換**mavenproject2-1.0-SNAPSHOT.jar**和**icns的名稱** MacOS ```bash /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/jpackage \ --type app-image \ --input target \ --name BingoGame \ --main-jar mavenproject2-1.0-SNAPSHOT.jar \ --main-class FinalProject.Run \ --java-options "--add-modules javafx.controls,javafx.fxml" \ --runtime-image javafx-jre \ --icon BingoIcon.icns \ --dest out ``` Windows PowerShell 打包為exe，以下指令並無包含ICON，Windwos所需的圖片格式需轉換為.ico ```bash jpackage --type app-image --input target --name BingoGame ` --main-jar mavenproject2-1.0-SNAPSHOT.jar ` --main-class FinalProject.Run ` --java-options "--add-modules javafx.controls,javafx.fxml" ` --runtime-image javafx-jre ` --dest out ``` 若之後你有正確 .ico，再加入這一行即可： ``` --icon BingoIcon.ico ` ``` 打包完成後你會在 out/BingoGame/ 看到： ``` BingoGame/ ├── BingoGame.exe ← 直接執行的主程式 ├── app/ ← 所有 jar、模組 ├── runtime/ ← jlink 的 JavaFX Runtime ├── BingoGame.cfg └── ... ``` ### mavenproject2-1.0-SNAPSHOT.jar 查看方法 使用以下命令來查看.jar位置和名字 ```bash ls target/*.jar ``` 結果顯示：target/**mavenproject2-1.0-SNAPSHOT.jar** 使用後面 **mavenproject2-1.0-SNAPSHOT.jar** 名稱即可 ```bash (base) 使用者@使用者 Bingo % ls target/*.jar target/mavenproject2-1.0-SNAPSHOT.jar ``` ### icns的名稱使用方法 ![CleanShot 2025-05-31 at 18.46.58](https://hackmd.io/_uploads/HkkVR8_fge.jpg) --icon BingoIcon.icns \ 為APP顯示之ICON，請自行更換名稱 * 將 BingoIcon.icns 放在你的專案根目錄（也就是 pom.xml 所在的資料夾） ``` mavenproject2/ ├── src/ ├── target/ ├── pom.xml ├── BingoIcon.icns ← 放這裡 ``` * .icns 檔案必須為 1024x1024 像素或轉換自 Apple Icon Image 工具（如[ cloudconvert](https://cloudconvert.com/png-to-icns)）產生，否則可能出錯或不顯示。 * 請勿放在 src 或 target 資料夾內，以免被 Maven 覆蓋或忽略。 --- > 成果位置：`out/BingoGame.app` --- ## 六、執行測試 ```bash open out/BingoGame.app ``` 或進入目錄後執行： ```bash cd out/BingoGame.app/Contents/MacOS/ ./BingoGame ``` --- ## （可選）打包成 `.dmg` 安裝檔 ```bash /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/jpackage \ --type dmg \ --input target \ --name BingoGame \ --main-jar mavenproject2-1.0-SNAPSHOT.jar \ --main-class FinalProject.Run \ --java-options "--add-modules javafx.controls,javafx.fxml" \ --runtime-image javafx-jre \ --icon BingoIcon.icns \ --dest out ``` --- > 產出：`out/BingoGame.dmg` ---