JDK 21 と JavaFX 22 の開発環境構築と HelloWorld アプリ作成ガイド

2026年7月2日

Contents

1 JDK 21 のインストールとパス設定
2 JavaFX 22 SDK の取得と環境変数設定
- 2.1 ダウンロードと解凍
- 2.2 環境変数 PATH_TO_FX を設定
3 IDE とビルドツールのセットアップ
4 プロジェクト構成とモジュール設定
- 4.1 module-info.java の基本構成（導入文）
- 4.2 Maven / Gradle と module‑info の連携（導入文）
5 Hello World アプリの作成と UI デザイン
6 ネイティブパッケージングとベストプラクティス
7 まとめ

スポンサードリンク

JDK 21 のインストールとパス設定

JDK 21 は LTS 版として Oracle 社や Eclipse Adoptium から配布されています。以下は Windows 環境を例にした手順です。他 OS（macOS / Linux）でも同様の流れでインストールできます。

ダウンロード
Windows: jdk-21_windows-x64_bin.exe
macOS (Intel): jdk-21_osx-x64_bin.dmg
macOS (Apple Silicon): jdk-21_osx-aarch64_bin.dmg
Linux: jdk-21_linux-x64_bin.tar.gz
インストール（デフォルト設定で問題ありません）
環境変数の設定

変数名	設定内容	補足
`JAVA_HOME`	JDK のインストールディレクトリ例 Windows: `C:\\Program Files\\Java\\jdk-21` macOS/Linux: `/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home`	必ずフルパスを指定してください。
`PATH`	`%JAVA_HOME%\\bin`（Windows） `$JAVA_HOME/bin`（macOS / Linux）	Windows はセミコロン `;`、Unix 系はコロン `:` で区切ります。

:: Windows の例（管理者権限のコマンドプロンプト）
setx JAVA_HOME &quot;C:\\Program Files\\Java\\jdk-21&quot;
setx PATH &quot;%PATH%;%JAVA_HOME%\\bin&quot;

:: Windows の例（管理者権限のコマンドプロンプト）

setx JAVA_HOME "C:\\Program Files\\Java\\jdk-21"

setx PATH "%PATH%;%JAVA_HOME%\\bin"

# macOS / Linux の例（~/.bash_profile などに追記）
export JAVA_HOME=&quot;/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home&quot;
export PATH=&quot;$PATH:$JAVA_HOME/bin&quot;

# macOS / Linux の例（~/.bash_profile などに追記）

export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home"

export PATH="$PATH:$JAVA_HOME/bin"

設定が完了したら、端末で次のコマンドを実行しバージョンが表示されることを確認します。

java -version
# 出力例
# java version &quot;21&quot; 2026-09-19 LTS
# Java(TM) SE Runtime Environment (build 21+35-2513)
# Java HotSpot(TM) 64-Bit Server VM (build 21+35-2513, mixed mode)

java -version

# 出力例

# java version "21" 2026-09-19 LTS

# Java(TM) SE Runtime Environment (build 21+35-2513)

# Java HotSpot(TM) 64-Bit Server VM (build 21+35-2513, mixed mode)

JavaFX 22 SDK の取得と環境変数設定

JavaFX は OpenJFX プロジェクトが提供するスタンドアロン SDK として配布されています。以下の手順でダウンロード・展開し、ビルドツールや IDE が参照できるように環境変数を設定します。

ダウンロードと解凍

OS	ダウンロード URL（例）
Windows	`https://download.openjfx.io/openjfx-22_windows-x64_bin-sdk.zip`
macOS (Intel)	`https://download.openjfx.io/openjfx-22_osx-x64_bin-sdk.zip`
macOS (Apple Silicon)	`https://download.openjfx.io/openjfx-22_osx-aarch64_bin-sdk.zip`
Linux	`https://download.openjfx.io/openjfx-22_linux-x64_bin-sdk.zip`

ダウンロードした zip を任意のディレクトリに展開します。例として Windows に展開した場合は次のようになります。

C:\javafx-sdk-22

1 2	C:\javafx-sdk-22

注意：Markdown のコードブロック内では Windows パスをエスケープするため、バックスラッシュは 2 つ書きます（C:\\javafx-sdk-22）。

環境変数 `PATH_TO_FX` を設定

公式ドキュメントでは PATH_TO_FX が推奨されており、IDE やビルドツールのデフォルト参照先として利用できます。JAVA_HOME と同様に OS 別の記法で設定してください。

:: Windows（管理者権限）
setx PATH_TO_FX &quot;C:\\javafx-sdk-22&quot;

:: Windows（管理者権限）

setx PATH_TO_FX "C:\\javafx-sdk-22"

# macOS / Linux（~/.bash_profile など）
export PATH_TO_FX=&quot;/opt/javafx-sdk-22&quot;

# macOS / Linux（~/.bash_profile など）

export PATH_TO_FX="/opt/javafx-sdk-22"

PATH へは JavaFX の実行ファイルが必要なケース（例: jpackage --runtime-image）だけ追加し、通常の開発では --module-path オプションで直接参照します。

:: 必要に応じて Windows の PATH に追加
setx PATH &quot;%PATH%;%PATH_TO_FX%\\bin&quot;

:: 必要に応じて Windows の PATH に追加

setx PATH "%PATH%;%PATH_TO_FX%\\bin"

設定が正しく反映されたか確認します。

echo %PATH_TO_FX%
rem =&gt; C:\javafx-sdk-22

echo %PATH_TO_FX%

rem => C:\javafx-sdk-22

IDE とビルドツールのセットアップ

IDE の導入と、Maven・Gradle それぞれの最小構成を比較します。ここでは IntelliJ IDEA Community Edition と Visual Studio Code を例に挙げますが、他のエディタでも同様の手順で設定できます。

IntelliJ IDEA Community の JavaFX サポート

IntelliJ IDEA 2024.2 以降は JavaFX ランタイムサポートが標準機能 として組み込まれています。プラグインを別途インストールする必要はありませんが、以下の手順で設定を確認すると安心です。

JetBrains の公式サイトから IntelliJ IDEA Community Edition をダウンロードしインストールします。
起動後、File → Project Structure → Modules でプロジェクトモジュールを選択し、Dependencies タブに javafx-controls・javafx-fxml が自動的に追加されているか確認します（無い場合は手動で Add → Library → From Maven を利用）。
Run/Debug 設定 で VM オプションに以下を追記し、モジュールパスを指示します。

--module-path $PATH_TO_FX/lib --add-modules=javafx.controls,javafx.fxml

1 2	--module-path $PATH_TO_FX/lib --add-modules=javafx.controls,javafx.fxml

ポイント：IDE のビルドツール（Maven/Gradle）と同様に --module-path を設定すれば、IDE 内でも実行・デバッグがシームレスになります。

Visual Studio Code の拡張機能

VS Code は軽量でプラグイン駆動のエディタです。以下の拡張を導入すると JavaFX 開発が快適になります。

拡張名	主な機能
Java Extension Pack (Red Hat)	Java 言語サポート、Maven/Gradle 連携
vscode-javafx	`javafx` ランタイムパス自動検出、コード補完
FXML Language Support	FXML シンタックスハイライト・バリデーション

拡張をインストールしたら、.vscode/settings.json に環境変数参照を追加します。

{
  &quot;javafx.sdk.path&quot;: &quot;${env:PATH_TO_FX}&quot;
}

{

"javafx.sdk.path": "${env:PATH_TO_FX}"

}

Maven と Gradle のテンプレート比較

共通前提

JDK 21 を使用（toolchain 設定推奨）
JavaFX SDK は PATH_TO_FX 環境変数で指すディレクトリに展開済み

以下のテンプレートは Java 9+ モジュラー構成 を前提としています。module-info.java と合わせて使用してください。

Maven（pom.xml）

&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot;
         xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
         xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 
                             https://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;
    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;

    &lt;groupId&gt;com.example&lt;/groupId&gt;
    &lt;artifactId&gt;HelloFX&lt;/artifactId&gt;
    &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;

    &lt;properties&gt;
        &lt;java.version&gt;21&lt;/java.version&gt;
        &lt;javafx.version&gt;22&lt;/javafx.version&gt;
        &lt;!-- 環境変数 PATH_TO_FX を参照 --&gt;
        &lt;javafx.sdk&gt;${env.PATH_TO_FX}&lt;/javafx.sdk&gt;
    &lt;/properties&gt;

    &lt;dependencies&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.openjfx&lt;/groupId&gt;
            &lt;artifactId&gt;javafx-controls&lt;/artifactId&gt;
            &lt;version&gt;${javafx.version}&lt;/version&gt;
        &lt;/dependency&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;org.openjfx&lt;/groupId&gt;
            &lt;artifactId&gt;javafx-fxml&lt;/artifactId&gt;
            &lt;version&gt;${javafx.version}&lt;/version&gt;
        &lt;/dependency&gt;
    &lt;/dependencies&gt;

    &lt;build&gt;
        &lt;plugins&gt;
            &lt;!-- コンパイル時にモジュールパスを設定 --&gt;
            &lt;plugin&gt;
                &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
                &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
                &lt;version&gt;3.12.1&lt;/version&gt;
                &lt;configuration&gt;
                    &lt;source&gt;${java.version}&lt;/source&gt;
                    &lt;target&gt;${java.version}&lt;/target&gt;
                    &lt;release&gt;${java.version}&lt;/release&gt;
                    &lt;compilerArgs&gt;
                        &lt;arg&gt;--module-path&lt;/arg&gt;
                        &lt;arg&gt;${javafx.sdk}/lib&lt;/arg&gt;
                        &lt;arg&gt;--add-modules&lt;/arg&gt;
                        &lt;arg&gt;javafx.controls,javafx.fxml&lt;/arg&gt;
                    &lt;/compilerArgs&gt;
                &lt;/configuration&gt;
            &lt;/plugin&gt;

            &lt;!-- exec:java で実行できるように設定 --&gt;
            &lt;plugin&gt;
                &lt;groupId&gt;org.codehaus.mojo&lt;/groupId&gt;
                &lt;artifactId&gt;exec-maven-plugin&lt;/artifactId&gt;
                &lt;version&gt;3.1.0&lt;/version&gt;
                &lt;configuration&gt;
                    &lt;mainClass&gt;com.example.hellofx.MainApp&lt;/mainClass&gt;
                    &lt;arguments&gt;&lt;/arguments&gt;
                    &lt;systemPropertyVariables&gt;
                        &lt;javafx.module.path&gt;${javafx.sdk}/lib&lt;/javafx.module.path&gt;
                    &lt;/systemPropertyVariables&gt;
                &lt;/configuration&gt;
            &lt;/plugin&gt;
        &lt;/plugins&gt;
    &lt;/build&gt;
&lt;/project&gt;

<project xmlns="http://maven.apache.org/POM/4.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0

https://maven.apache.org/xsd/maven-4.0.0.xsd">

<groupId>com.example</groupId>

<artifactId>HelloFX</artifactId>

<version>1.0-SNAPSHOT</version>

<java.version>21</java.version>

<javafx.version>22</javafx.version>

<javafx.sdk>${env.PATH_TO_FX}</javafx.sdk>

</properties>

<groupId>org.openjfx</groupId>

<artifactId>javafx-controls</artifactId>

<version>${javafx.version}</version>

</dependency>

<groupId>org.openjfx</groupId>

<artifactId>javafx-fxml</artifactId>

<version>${javafx.version}</version>

</dependency>

</dependencies>

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

<source>${java.version}</source>

<target>${java.version}</target>

<release>${java.version}</release>

<arg>--module-path</arg>

<arg>${javafx.sdk}/lib</arg>

<arg>--add-modules</arg>

<arg>javafx.controls,javafx.fxml</arg>

</compilerArgs>

</configuration>

</plugin>

<groupId>org.codehaus.mojo</groupId>

<artifactId>exec-maven-plugin</artifactId>

<mainClass>com.example.hellofx.MainApp</mainClass>

<javafx.module.path>${javafx.sdk}/lib</javafx.module.path>

</systemPropertyVariables>

</configuration>

</plugin>

</plugins>

</build>

</project>

Gradle（build.gradle）

plugins {
    id 'application'
    id 'org.openjfx.javafxplugin' version '0.1.0' // 公式プラグイン
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

// 環境変数 PATH_TO_FX を参照
def fxSdk = System.getenv('PATH_TO_FX')

repositories {
    mavenCentral()
}

dependencies {
    implementation &quot;org.openjfx:javafx-controls:${javafx.version}&quot;
    implementation &quot;org.openjfx:javafx-fxml:${javafx.version}&quot;
}

// JavaFX プラグイン設定（module-path の自動生成）
javafx {
    version = '22'
    modules = [ 'javafx.controls', 'javafx.fxml' ]
    // 手動で module‑path を上書きしたい場合
    // sdk = file(fxSdk)
}

application {
    mainModule = 'com.example.hellofx'
    mainClass = 'com.example.hellofx.MainApp'
}

plugins {

id 'application'

id 'org.openjfx.javafxplugin' version '0.1.0' // 公式プラグイン

}

java {

toolchain {

languageVersion = JavaLanguageVersion.of(21)

}

// 環境変数 PATH_TO_FX を参照

def fxSdk = System.getenv('PATH_TO_FX')

repositories {

mavenCentral()

}

dependencies {

implementation "org.openjfx:javafx-controls:${javafx.version}"

implementation "org.openjfx:javafx-fxml:${javafx.version}"

}

// JavaFX プラグイン設定（module-path の自動生成）

javafx {

version = '22'

modules = [ 'javafx.controls', 'javafx.fxml' ]

// 手動で module‑path を上書きしたい場合

// sdk = file(fxSdk)

}

application {

mainModule = 'com.example.hellofx'

mainClass = 'com.example.hellofx.MainApp'

}

選び方のポイント

ビルドツール	メリット	デメリット
Maven	プロジェクト構造が標準化されており、企業向けで信頼性が高い	XML が冗長になることがある
Gradle	DSL がシンプルで高速。プラグインが豊富	初学者には Groovy/Kotlin の文法がややハードル

プロジェクト構成とモジュール設定

Java 9 以降は module‑system がデフォルトです。この章では最低限必要な module-info.java と、IDE・ビルドツールとの連携ポイントを解説します。

module-info.java の基本構成（導入文）

以下のファイルは src/main/java/module-info.java に配置し、プロジェクト全体で使用する JavaFX モジュールを宣言します。モジュール化により不要なクラスがランタイムに含まれず、パッケージサイズが小さくなります。

module com.example.hellofx {
    // 必要な JavaFX コアモジュール
    requires javafx.controls;
    requires javafx.fxml;

    // FXML がリフレクションでコントローラにアクセスできるように開放
    opens com.example.hellofx to javafx.fxml;

    // アプリケーション側のパブリック API を外部へ公開
    exports com.example.hellofx;
}

module com.example.hellofx {

// 必要な JavaFX コアモジュール

requires javafx.controls;

requires javafx.fxml;

// FXML がリフレクションでコントローラにアクセスできるように開放

opens com.example.hellofx to javafx.fxml;

// アプリケーション側のパブリック API を外部へ公開

exports com.example.hellofx;

}

ポイント
- requires は実際に使用するモジュールだけ列挙します。不要なモジュールは省くほどイメージが軽くなります。
- opens ... to javafx.fxml が無いと、FXML のコントローラで @FXML フィールドやハンドラが認識されません。

Maven / Gradle と module‑info の連携（導入文）

Maven と Gradle の両方とも、上記 module-info.java を自動的にコンパイル対象に含めます。ここで重要なのは モジュールパスの指定 です。ビルドプラグインが --module-path ${PATH_TO_FX}/lib を付与することで、IDE でも同様の環境が再現されます。

ビルドツール	モジュールパス設定例
Maven	`<arg>--module-path</arg><arg>${javafx.sdk}/lib</arg>`
Gradle (JavaFX プラグイン)	`javafx { ... }` が内部で `--module-path` を生成

Hello World アプリの作成と UI デザイン

ここでは コードベース と FXML + Scene Builder の 2 通りで「Hello World」アプリを実装します。両方の手順を示すことで、プロジェクトの拡張性や保守性の違いが分かります。

コードベースでのシンプル実装（導入文）

最小限の JavaFX アプリは Application を継承し、start() メソッド内でシーンを構築します。以下は Windows パス表記もエスケープした形です。

package com.example.hellofx;

import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.control.Label;
import javafx.stage.Stage;

public class MainApp extends Application {
    @Override
    public void start(Stage primaryStage) {
        Label hello = new Label(&quot;Hello, JavaFX 22!&quot;);
        Scene scene = new Scene(hello, 400, 200);
        primaryStage.setTitle(&quot;JavaFX HelloWorld&quot;);
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

package com.example.hellofx;

import javafx.application.Application;

import javafx.scene.Scene;

import javafx.scene.control.Label;

import javafx.stage.Stage;

public class MainApp extends Application {

@Override

public void start(Stage primaryStage) {

Label hello = new Label("Hello, JavaFX 22!");

Scene scene = new Scene(hello, 400, 200);

primaryStage.setTitle("JavaFX HelloWorld");

primaryStage.setScene(scene);

primaryStage.show();

}

public static void main(String[] args) {

launch(args);

}

実行手順（Maven）

mvn clean compile exec:java \
  -Dexec.mainClass=com.example.hellofx.MainApp \
  -Dexec.args=&quot;&quot;

mvn clean compile exec:java \

-Dexec.mainClass=com.example.hellofx.MainApp \

-Dexec.args=""

実行手順（Gradle）

./gradlew run

1 2	./gradlew run

FXML と Scene Builder を使った UI 作成（導入文）

FXML は UI のレイアウトを XML で記述でき、デザイナー (Scene Builder) とコードの分離が容易です。

Scene Builder のインストール
公式スタンドアロン版は https://gluonhq.com/products/scene-builder/ からダウンロードし、PATH に追加しておくと scenebuilder コマンドで起動できます。
FXML ファイル作成（src/main/resources/com/example/hellofx/MainView.fxml）

&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;?import javafx.scene.control.Label?&gt;
&lt;?import javafx.scene.layout.StackPane?&gt;

&lt;StackPane xmlns:fx=&quot;http://javafx.com/fxml/22&quot;
           fx:controller=&quot;com.example.hellofx.MainController&quot;&gt;
    &lt;Label text=&quot;Hello, JavaFX with FXML!&quot; /&gt;
&lt;/StackPane&gt;

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.Label?>

<?import javafx.scene.layout.StackPane?>

<StackPane xmlns:fx="http://javafx.com/fxml/22"

fx:controller="com.example.hellofx.MainController">

</StackPane>

コントローラ（空実装で OK）

package com.example.hellofx;

import javafx.fxml.FXML;

/**
 * 画面ロジックはここに記述します。今回はデモなので空です。
 */
public class MainController {
    // 例: @FXML private Button myButton;
}

package com.example.hellofx;

import javafx.fxml.FXML;

/**

* 画面ロジックはここに記述します。今回はデモなので空です。

public class MainController {

// 例: @FXML private Button myButton;

}

起動クラス（FXML 読み込み版）

package com.example.hellofx;

import javafx.application.Application;
import javafx.fxml.FXMLLoader;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.stage.Stage;

public class MainApp extends Application {
    @Override
    public void start(Stage stage) throws Exception {
        Parent root = FXMLLoader.load(
                getClass().getResource(&quot;/com/example/hellofx/MainView.fxml&quot;));
        Scene scene = new Scene(root, 400, 200);
        stage.setTitle(&quot;JavaFX FXML HelloWorld&quot;);
        stage.setScene(scene);
        stage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

package com.example.hellofx;

import javafx.application.Application;

import javafx.fxml.FXMLLoader;

import javafx.scene.Parent;

import javafx.scene.Scene;

import javafx.stage.Stage;

public class MainApp extends Application {

@Override

public void start(Stage stage) throws Exception {

Parent root = FXMLLoader.load(

getClass().getResource("/com/example/hellofx/MainView.fxml"));

Scene scene = new Scene(root, 400, 200);

stage.setTitle("JavaFX FXML HelloWorld");

stage.setScene(scene);

stage.show();

}

public static void main(String[] args) {

launch(args);

}

ポイント：FXMLLoader.load() の引数はクラスパス上のリソースを表すので、必ず / から始めるか getResourceAsStream を利用してください。

デバッグ時によくあるエラーと対処法（導入文）

エラーメッセージ	主な原因	推奨対策
`java.lang.module.FindException: Module javafx.controls not found`	ビルドツールの module‑path が未設定	Maven/Gradle の `compilerArgs` に `--module-path ${PATH_TO_FX}/lib` を追記し、IDE の Run Configuration でも同様に設定
`javafx.fxml.LoadException: Cannot resolve resource`	FXML ファイルがクラスパス上に見つからない	`src/main/resources` 配下に配置し、ビルド後の JAR に含まれているか確認 (`jar tf target/*.jar`)
`IllegalStateException: Toolkit not initialized`	JavaFX スレッド外で UI 操作を行った	UI 更新は必ず `Platform.runLater(() -> { /* UI code */ })` または `Task<V>` を使用
`java.lang.NoClassDefFoundError: javafx/application/Application`	JRE がモジュラーモードで起動していない	`--module-path` と `--add-modules=javafx.controls,javafx.fxml` を VM オプションに追加

ネイティブパッケージングとベストプラクティス

完成したアプリを OS 固有の実行可能形式（.exe、.dmg、.deb 等）に変換すれば、エンドユーザーは JDK を別途インストールする必要がなくなります。公式が推奨する手順は jlink + jpackage の組み合わせです。

1. `jlink` で最小ランタイムイメージを作成（導入文）

# Windows / macOS / Linux 共通
jlink \
  --module-path &quot;$PATH_TO_FX/lib:$(jdeps --print-module-deps target/hellofx.jar)&quot; \
  --add-modules com.example.hellofx,javafx.controls,javafx.fxml \
  --output dist/runtime \
  --compress=2 \
  --no-header-files \
  --no-man-pages

# Windows / macOS / Linux 共通

jlink \

--module-path "$PATH_TO_FX/lib:$(jdeps --print-module-deps target/hellofx.jar)" \

--add-modules com.example.hellofx,javafx.controls,javafx.fxml \

--output dist/runtime \

--compress=2 \

--no-header-files \

--no-man-pages

--module-path は JavaFX SDK の lib ディレクトリ と、アプリケーション JAR が依存しているモジュールをカンマ区切りで指定します。
Windows ではパス区切り文字はセミコロン ;、Unix 系（macOS / Linux）ではコロン : を使用してください。

2. `jpackage` によるインストーラ作成（導入文）

OS	主なオプション例
Windows	`bash jpackage \`
--type exe \
--name HelloFX \
--app-version 1.0.0 \
--input target/classes \
--main-jar hellofx.jar \
--module-path "$PATH_TO_FX/lib;dist/runtime" \
--main-module com.example.hellofx/com.example.hellofx.MainApp \
--win-console \
--win-dir-chooser \
--icon src/main/resources/icon.ico
macOS	`bash jpackage \`
--type dmg \
--name HelloFX \
--app-version 1.0.0 \
--input target/classes \
--main-jar hellofx.jar \
--module-path "$PATH_TO_FX/lib:dist/runtime" \
--main-module com.example.hellofx/com.example.hellofx.MainApp \
--icon src/main/resources/icon.icns \
--mac-package-identifier com.example.hellofx \
--mac-sign \
--mac-notarization=none
Linux (Debian/Ubuntu)	`bash jpackage \`
--type deb \
--name hello-fx \
--app-version 1.0.0 \
--input target/classes \
--main-jar hellofx.jar \
--module-path "$PATH_TO_FX/lib:dist/runtime" \
--main-module com.example.hellofx/com.example.hellofx.MainApp \
--icon src/main/resources/icon.png \
--linux-shortcut \
--linux-package-name hello-fx \
--linux-deb-maintainer "Your Name you@example.com" \
--linux-rpm-license GPL-3.0+

macOS のサンドボックス化（追加説明）

macOS で配布する場合は、App Sandbox が必要になるケースがあります。jpackage では次のオプションで有効化できます。

--mac-app-category=public.app-category.developer-tools \
--mac-entitlements=src/main/resources/entitlements.plist

--mac-app-category=public.app-category.developer-tools \

--mac-entitlements=src/main/resources/entitlements.plist

entitlements.plist は Apple のドキュメントに沿って作成し、ファイルアクセスやネットワーク権限を宣言します。

Linux の依存関係（追加説明）

Debian 系ディストリビューションでは GTK3 が必要です。インストールが不足していると起動時に java.lang.UnsatisfiedLinkError: libgtk-3.so が発生します。配布パッケージに次の依存関係を明示してください。

--linux-deb-options=&quot;--depends=libgtk-3-0&quot;

1 2	--linux-deb-options="--depends=libgtk-3-0"

3. 開発時に避けるべき落とし穴と推奨手法（導入文）

項目	落とし穴例	ベストプラクティス
リソースパス	`getResource("image.png")` が `null` になる	リソースは必ず `src/main/resources` 配下に配置し、取得時は `/com/example/.../image.png` のように絶対パスで参照
マルチモジュール構成	依存関係が曖昧になりコンパイルエラー	各機能をサブモジュール化し、`requires transitive` で公開範囲を制御。`module-info.java` は常に最新の依存リストに保つ
UI スレッド管理	バックグラウンドタスクから直接 UI を更新 → `Not on FX application thread` エラー	`javafx.concurrent.Task<V>` や `Service` クラスで非同期処理し、完了ハンドラは `Platform.runLater` で UI に反映
ビルドツールのバージョン	古い Maven が Java 21 の `toolchain` を認識できない	ビルドプラグインは常に最新版（Maven 3.9+、Gradle 8.x）を使用し、`mvn -v` / `gradle --version` で確認
パッケージング時の OS 固有設定	Windows の `--win-console` を付け忘れ、コンソールが表示されずデバッグ困難	各 OS 用スクリプトを別ファイルに分割し、CI/CD パイプラインで自動生成する

まとめ

JDK 21 と JavaFX 22（リリース前） を環境変数 JAVA_HOME / PATH_TO_FX で管理し、OS 毎のパス区切り文字に注意すればどのプラットフォームでも同一手順が適用可能です。
IntelliJ IDEA は標準で JavaFX サポートを提供しているため、追加プラグインは必須ではありませんが、VM オプションでモジュールパスを明示すると確実です。
Maven と Gradle のテンプレート を使い分けることで、チームやプロジェクト規模に合わせたビルド環境が構築できます。
module-info.java によるモジュール化はランタイムサイズ削減とセキュリティ向上に直結します。必ず requires と opens を正しく記述してください。
jlink + jpackage の組み合わせで、Windows .exe, macOS .dmg, Linux .deb/.rpm へ容易にパッケージングできます。macOS のサンドボックスや Linux の GTK 依存関係など OS 固有のオプションを忘れずに設定してください。

以上の手順とベストプラクティスに従えば、初心者でも安全かつ効率的に JavaFX アプリ開発環境を構築し、クロスプラットフォーム向けに配布できるようになります。 Happy coding!

スポンサードリンク

-JavaFX

comment コメントをキャンセル

: JavaFX

JavaFX 18 新 UI コンポーネントと高速化ベストプラクティス

JavaFX 18 が提供する高速描画とモダン UI を、ハードウェアアクセラレーションやバッチ描画、FXML/Scene Builder の実践的手順で徹底解説します。

: JavaFX

JavaFX 2026新機能とOpenJFX/SDK比較ガイド

JavaFX 2026年の3Dエンジン強化やCSS拡張機能、OpenJFXとJavaFX SDKの技術的違いを解説。Red Hatサポート状況や最新SDK導入手順も紹介。

: JavaFX

2026年版無料JavaFX企業向けUIテンプレートまとめと導入ガイド

最新無料JavaFX UIテンプレートと実務での活用ポイントを一目で把握できます。

: JavaFX

JavaFX 22 と Scene Builder 23 の最新情報と開発環境構築ガイド

JavaFX 22 と Scene Builder 23 の新機能やインストール方法、Maven/Gradle 設定、FXML・CSS 活用までを実践的に解説します。

: JavaFX

JavaFX 21環境構築Eclipse完全ガイド

JavaFX 21環境構築に関する完全ガイドです。Eclipseでの導入手順、Maven/Gradle設定、SceneBuilder連携などを網羅して解説しています。

Electronアプリ開発入門：環境構築・基本コード・ビルド手順

SwiftUI macOS アプリの公開手順と公証完全ガイド

JDK 21 と JavaFX 22 の開発環境構築と HelloWorld アプリ作成ガイド

JDK 21 のインストールとパス設定

JavaFX 22 SDK の取得と環境変数設定

ダウンロードと解凍

環境変数 PATH_TO_FX を設定

IDE とビルドツールのセットアップ

IntelliJ IDEA Community の JavaFX サポート

Visual Studio Code の拡張機能

Maven と Gradle のテンプレート比較

共通前提

Maven（pom.xml）

Gradle（build.gradle）

プロジェクト構成とモジュール設定

module-info.java の基本構成（導入文）

Maven / Gradle と module‑info の連携（導入文）

Hello World アプリの作成と UI デザイン

コードベースでのシンプル実装（導入文）

実行手順（Maven）

実行手順（Gradle）

FXML と Scene Builder を使った UI 作成（導入文）

デバッグ時によくあるエラーと対処法（導入文）

ネイティブパッケージングとベストプラクティス

1. jlink で最小ランタイムイメージを作成（導入文）

2. jpackage によるインストーラ作成（導入文）

macOS のサンドボックス化（追加説明）

Linux の依存関係（追加説明）

3. 開発時に避けるべき落とし穴と推奨手法（導入文）

まとめ

JDK 21 と JavaFX 22 の開発環境構築と HelloWorld アプリ作成ガイド

JDK 21 のインストールとパス設定

JavaFX 22 SDK の取得と環境変数設定

環境変数 `PATH_TO_FX` を設定

1. `jlink` で最小ランタイムイメージを作成（導入文）

2. `jpackage` によるインストーラ作成（導入文）