本文旨在解决使用gradle、javafx和jlink打包应用时常见的“duplicate module on application module path”错误。该错误通常由于依赖项冲突，特别是第三方库重复引入javafx模块所致。文章将详细分析问题根源，并提供通过gradle依赖排除机制解决此问题的具体步骤和示例代码，确保模块路径的纯净性，从而成功构建和打包模块化javafx应用。
1. 问题概述与错误分析
在使用Gradle构建JavaFX应用程序并尝试通过jlink命令打包时，开发者可能会遇到error: duplicate module on application module path的错误。这个错误通常发生在createMergedModule任务执行期间，导致构建失败。错误信息会明确指出哪些JavaFX模块（例如javafx.base、javafx.controls）在应用程序模块路径上重复。
示例错误信息：
> Task :createMergedModule error: duplicate module on application module path module in javafx.base error: duplicate module on application module path module in javafx.controls 2 errors > Task :createMergedModule FAILED
此问题的核心在于Java模块系统（Jigsaw）要求每个模块在模块路径上只能出现一次。当构建工具（如Gradle）在准备应用程序的模块图时，如果发现同一个模块（例如javafx.base）被多个来源引入，就会抛出此错误。
2. 问题根源探究
导致“duplicate module on application module path”错误的主要原因通常是：
立即学习“Java免费学习笔记（深入）”；
- 第三方依赖项传递性引入JavaFX模块： 许多JavaFX相关的第三方库（如aerofx、controlsfx等）可能在其自身的依赖声明中包含了JavaFX模块。当这些库被添加到项目的dependencies块中时，它们会通过传递性依赖将JavaFX模块引入到项目中。
- org.openjfx.javafxplugin插件的机制： org.openjfx.javafxplugin插件已经负责管理和引入正确版本的JavaFX模块。如果其他库再次引入这些模块，就会与插件管理的模块发生冲突。
- 构建环境或缓存问题： 在某些情况下，构建目录（如build/jlinkbase/jlinkjars）中可能残留了针对不同平台或重复的JavaFX模块JAR包，导致模块路径污染。这在跨平台开发环境（如WSL）中尤其需要注意。
在提供的build.gradle配置中，我们看到org.openjfx.javafxplugin插件被正确应用，并且javafx块明确指定了javafx.controls和javafx.fxml模块。同时，项目依赖了多个第三方库，例如org.aerofx:aerofx和org.controlsfx:controlsfx。这些库是潜在的JavaFX模块重复引入者。
3. 解决方案：依赖排除
解决此问题的核心策略是识别并排除那些由第三方依赖项传递性引入的重复JavaFX模块。Gradle的依赖管理机制允许我们对特定依赖项进行排除（exclude）操作。
3.1 识别“污染”的依赖项
要确定哪个第三方库正在重复引入JavaFX模块，可以采取以下方法：
- 检查build/jlinkbase/jlinkjars目录： 在构建失败后，检查此目录。如果其中包含多个相同JavaFX模块（例如javafx.base.jar、javafx.controls.jar）但来源不同的文件，则表明存在冲突。
- 使用gradle dependencies命令： 运行gradle dependencies --configuration implementation（或针对特定配置），查看完整的依赖树。仔细检查每个第三方库的子依赖，看是否有org.openjfx组下的JavaFX模块。
通常，像org.controlsfx:controlsfx这样的库是为JavaFX应用程序设计的，它们可能在其内部声明对JavaFX模块的依赖。虽然它们通常会声明为provided或compileOnly以避免冲突，但有时配置不当或版本不兼容会导致问题。
3.2 应用依赖排除规则
一旦识别出可能导致冲突的第三方库，就可以在build.gradle文件中使用exclude关键字来排除其传递性JavaFX依赖。
步骤：
- 定位问题依赖： 根据识别结果，找到dependencies块中对应的implementation（或其他配置）语句。
- 添加排除规则： 在该依赖项的声明后面添加一个闭包，使用exclude group: 'org.openjfx'来排除所有来自org.openjfx组的传递性依赖。
示例代码：
假设org.aerofx:aerofx和org.controlsfx:controlsfx是导致JavaFX模块重复引入的潜在来源。我们可以这样修改build.gradle：
// 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" // 确保JavaFX版本与项目需求一致
modules = [ 'javafx.controls', 'javafx.fxml' ]
}
dependencies {
// 假设aerofx可能重复引入JavaFX模块，进行排除
implementation("org.aerofx:aerofx:0.2") {
exclude group: 'org.openjfx'
}
// 假设controlsfx可能重复引入JavaFX模块，进行排除
implementation("org.controlsfx:controlsfx:11.0.3") {
exclude group: 'org.openjfx'
}
// 其他依赖保持不变
implementation "pdfbox:pdfbox:0.7.3"
implementation "org.javatuples:javatuples:1.2"
implementation "org.mariadb.jdbc:mariadb-java-client:2.1.2"
implementation "io.gitlab.vincent-lambert:miscellaneousWidgets:1.7"
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']
}
}注意事项：
- 精确排除： exclude group: 'org.openjfx'会排除所有来自该组的依赖。如果某个库确实需要其自身捆绑的JavaFX特定组件（这很少见且通常是不推荐的做法），则需要更精细的排除，例如exclude module: 'javafx.base'。但在大多数情况下，排除整个org.openjfx组是安全的，因为org.openjfx.javafxplugin已经提供了所需的JavaFX模块。
- 逐一排查： 如果不确定是哪个库导致的问题，可以尝试对每个可疑的第三方依赖项逐一添加排除规则，然后重新构建，直到错误消失。
- 清理构建缓存： 在修改build.gradle后，建议运行gradle clean清除旧的构建产物，然后再次运行gradle jlink，以确保新的依赖规则生效。
4. 总结
“duplicate module on application module path”错误是模块化JavaFX应用在打包过程中常见的障碍。通过理解其根源——即第三方库传递性引入重复的JavaFX模块——我们可以利用Gradle强大的依赖管理功能，通过exclude规则精确地解决这个问题。这种方法确保了模块路径的纯净性，使得jlink能够成功地创建自定义运行时镜像，从而实现JavaFX应用的顺畅打包和分发。在进行依赖管理时，始终建议保持对项目依赖树的清晰认识，并定期检查是否存在潜在的冲突。
