JavaFX Jlink打包重复模块问题解决方法

在Gradle构建JavaFX应用并使用Jlink打包时，开发者常遇到“duplicate module on application module path”错误，尤其涉及`javafx.base`或`javafx.controls`。本教程深入分析此问题，指出其根源在于第三方库的传递性依赖可能重复引入JavaFX模块，并提供了一套行之有效的解决方案：通过在`build.gradle`中精确排除`org.openjfx`组下的传递性依赖，确保Jlink构建流程的模块路径清晰无冲突。

引言：Jlink与JavaFX模块化打包面临的挑战

JavaFX应用程序结合Java模块系统（Jigsaw）和Jlink工具进行打包，能够创建轻量级、自包含的运行时镜像，极大地简化了部署。然而，在这一过程中，一个常见且令人困扰的问题是“duplicate module on application module path”错误。当执行gradle jlink命令时，构建过程可能因发现模块路径上存在重复的JavaFX模块而失败，例如javafx.base或javafx.controls。这通常发生在项目使用了org.openjfx.javafxplugin插件来管理JavaFX依赖，同时又引入了某些第三方库，而这些库在其传递性依赖中也包含了JavaFX模块时。

深入理解重复模块错误

Jlink工具在构建自定义运行时镜像时，会分析应用程序的模块依赖图。如果发现同一个模块（由其模块名标识）在模块路径上被声明了多次，就会抛出error: duplicate module on application module path。

在JavaFX项目中，出现此错误的原因通常是：

1. org.openjfx.javafxplugin插件的作用：该插件负责将正确版本的JavaFX模块（如javafx.controls, javafx.fxml等）添加到项目的模块路径中，并确保它们与当前操作系统兼容。
2. 第三方库的传递性依赖：项目中引入的某些第三方库（例如UI组件库、网络库或任何可能间接依赖JavaFX的库）可能在其自身的pom.xml或build.gradle中声明了对JavaFX模块的依赖。当Gradle解析这些依赖时，它会将这些传递性JavaFX模块也拉入项目的模块路径。
3. 冲突的产生：如果第三方库传递引入的JavaFX模块与org.openjfx.javafxplugin插件提供的JavaFX模块是同一个（即具有相同的模块名），Jlink就会检测到重复，并终止构建。

例如，错误信息中module in javafx.base和module in javafx.controls明确指出，javafx.base和javafx.controls这两个核心JavaFX模块被重复发现了。

解决方案：排除重复的传递性依赖

解决此问题的核心策略是识别并排除那些由第三方库传递引入的重复JavaFX模块。Gradle的依赖管理机制提供了强大的exclude功能，允许我们从特定依赖的传递性闭包中移除不需要的组件。

步骤一：识别潜在的“污染”库

首先，需要确定哪个或哪些第三方库是导致重复模块问题的源头。这可以通过以下方法进行：

• 观察错误信息：虽然错误信息直接指出了重复的JavaFX模块，但并未直接指明是哪个第三方库引入的。
• 检查build/jlinkbase/jlinkjars目录：在Jlink构建失败后，检查build/jlinkbase/jlinkjars目录。如果该目录中包含了同一JavaFX模块的多个版本或针对不同平台的JAR包（例如，同时有macOS和Windows版本的javafx.base.jar），则很可能存在冲突。
• 使用Gradle依赖分析工具：运行gradle dependencies命令可以生成详细的依赖树。仔细检查依赖树，查找哪些第三方库下面包含了org.openjfx组下的JavaFX模块。

根据经验，一些与UI或图形相关的库，或者那些没有严格遵循Java模块系统最佳实践的旧库，更容易引入此类问题。在提供的案例中，aerofx、controlsfx或miscellaneousWidgets等都可能是潜在的怀疑对象。

步骤二：在build.gradle中排除冲突模块

一旦识别出潜在的“污染”库，就可以使用exclude规则将其传递引入的org.openjfx组下的模块排除掉。

以下是修改build.gradle文件的示例：

plugins {
  id 'java'
  id 'org.openjfx.javafxplugin' version '0.0.13'
  id 'org.beryx.jlink' version '2.16.2'
}

repositories {
    mavenCentral()
    mavenLocal()
}

javafx {
    version = "19"
    modules = [ 'javafx.controls', 'javafx.fxml' ]
}

dependencies {
    // 假设 aerofx 或 miscellaneousWidgets 可能传递引入了重复的 JavaFX 模块
    implementation "org.aerofx:aerofx:0.2" {
        // 排除 org.openjfx 组下的所有模块
        exclude group: 'org.openjfx'
    }
    implementation "pdfbox:pdfbox:0.7.3"
    implementation "org.javatuples:javatuples:1.2"
    implementation "org.controlsfx:controlsfx:11.0.3" {
        // ControlsFX 是基于 JavaFX 的，通常不会直接引入冲突，
        // 但如果遇到问题，也可以尝试排除。
        // 一般来说，javafxplugin 会正确处理 ControlsFX 的 JavaFX 依赖。
        // exclude group: 'org.openjfx'
    }
    implementation "org.mariadb.jdbc:mariadb-java-client:2.1.2"
    implementation "io.gitlab.vincent-lambert:miscellaneousWidgets:1.7" {
        // 排除 org.openjfx 组下的所有模块
        exclude group: 'org.openjfx'
    }
    implementation "org.apache.httpcomponents:httpclient:4.5.13"
    implementation "org.apache.httpcomponents:httpmime:4.3.1"
}

application {
    mainModule = 'CharacterCreator'
    mainClass = 'CharacterCreator.Menu.App'
}

tasks.withType(JavaCompile) {
    options.compilerArgs << '-Xlint:unchecked'
    options.deprecation = true
}

jlink {
    options = ['--strip-debug', '--compress', '2', '--no-header-files', '--no-man-pages']
    launcher{
        name = 'hello'
        jvmArgs = ['-Dlog4j.configurationFile=./log4j2.xml']
    }
}

代码解释： 在dependencies块中，对于你怀疑会引入重复JavaFX模块的implementation声明，添加一个闭包，并在其中使用exclude group: 'org.openjfx'。这会告诉Gradle，在解析该特定依赖的传递性依赖时，忽略任何来自org.openjfx组的模块。由于org.openjfx.javafxplugin已经正确地管理了官方JavaFX模块，这种排除并不会导致JavaFX功能缺失，反而消除了重复。

步骤三：重新构建并验证

修改build.gradle后，执行以下命令清理并重新构建项目：

gradle clean jlink

如果问题得到解决，jlink任务将成功完成，生成自包含的运行时镜像。

注意事项与最佳实践

• 精确排除：如果exclude group: 'org.openjfx'过于宽泛，可能会不小心排除掉某个第三方库确实需要且未被javafxplugin覆盖的JavaFX相关模块。在大多数情况下，对于核心JavaFX模块，这种宽泛排除是安全的。如果遇到新的问题，可以尝试更精确地排除，例如exclude group: 'org.openjfx', module: 'javafx-base'。
• 依赖树分析：熟练使用gradle dependencies命令是调试此类问题的利器。它能清晰展示所有依赖及其传递性关系，帮助你准确找出哪个库引入了冲突。
• 模块系统兼容性：在选择第三方库时，尽量优先选择那些明确支持Java模块系统（Jigsaw）的库。这些库通常会正确声明其模块信息，并避免引入不必要的传递性依赖。
• 跨平台打包：此解决方案对于在WSL（Windows Subsystem for Linux）等环境中构建跨平台（如Linux和Windows）可执行文件同样有效。确保你的javafx插件配置正确，并且Jlink能够访问到对应平台的JavaFX SDK。

总结

“duplicate module on application module path”错误是Gradle JavaFX Jlink打包过程中常见的挑战，但通过理解其产生原因——第三方库传递性引入重复JavaFX模块——并运用Gradle的exclude机制，可以有效地解决。精确识别并排除冲突模块，能够确保Jlink构建流程的顺畅，从而成功创建出高效、自包含的JavaFX应用程序运行时镜像。